Skip to main content
The projects endpoints let you retrieve your project’s details, update its headline and page content, create announcements, and push updated command definitions to Top.gg. These endpoints are scoped to the authenticated token, so you can only access your own project.
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/@me

Returns the project associated with your current token. 
curl https://top.gg/api/v1/projects/@me \
  -H "Authorization: Bearer $TOPGG_TOKEN"

​
Response fields

​
id
string
required
The unique Top.gg-sourced Snowflake identifier for the project.
​
name
string
required
The project name as it appears on the external platform.
​
platform
string
required
The platform the project belongs to. One of discord or roblox.
​
type
string
required
The project type. One of bot, server, or game.
​
headline
string
required
The short description set during project creation.
​
tags
string[]
required
List of tag IDs associated with the project.
​
votes
number
required
Current vote count used for ranking calculations.
​
votes_total
number
required
Total all-time votes received by the project.
​
review_score
number
required
Average review score across all reviews.
​
review_count
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/@me

Updates the headline and/or page content for your project. Both fields are locale-keyed, so you can set content for multiple languages in a single request. 
curl -X PATCH https://top.gg/api/v1/projects/@me \
  -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..."
    }
  }'

​
Request body

At least one of headline or page_content must be provided.
​
headline
object
A map of locale codes to headline strings. Each headline must be between 3 and 140 characters.
​
page_content
object
A map of locale codes to page content strings (Markdown supported). Each entry must be between 300 and 50,000 characters.

​
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

StatusDescription
400Invalid project token
404Project not found
422Validation error (unsupported locale, length violations, or missing fields)

​
PUT /projects/@me/announcements

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 PUT https://top.gg/api/v1/projects/@me/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."
  }'

​
Request body

​
title
string
required
The announcement title. Must be between 3 and 100 characters.
​
content
string
required
The announcement body text. Must be between 10 and 2,000 characters.

​
Response fields

​
title
string
required
The title of the created announcement.
​
content
string
required
The body content of the created announcement.
​
created_at
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

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

​
POST /projects/@me/metrics

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 POST https://top.gg/api/v1/projects/@me/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

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

​
POST /projects/@me/metrics/batch

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/@me/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

​
data
object[]
required
The batch of metrics entries. Must contain between 1 and 100 entries.

​
Response

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

​
Error responses

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

​
Platform payloads

The metrics payload is shaped per platform. For POST /projects/@me/metrics, send this payload as the entire 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.
​
server_count
integer
Total number of servers the bot is currently in. Must be zero or greater.
​
shard_count
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.
​
member_count
integer
Total number of members in the server. Must be zero or greater.
​
online_count
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".
​
player_count
integer
required
Current number of players in the game. Must be zero or greater.
{
  "player_count": 428
}

​
POST /projects/@me/commands

Updates the 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 POST https://top.gg/api/v1/projects/@me/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.
​
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.