> ## Documentation Index
> Fetch the complete documentation index at: https://docs.top.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API Endpoints for Projects

> Use the /projects/@me endpoints to retrieve project details, update headline and page content, create announcements, and update Discord slash commands. Requires a valid Bearer token.

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.

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

## GET /projects/@me

Returns the project associated with your current token.

```bash theme={null}
curl https://top.gg/api/v1/projects/@me \
  -H "Authorization: Bearer $TOPGG_TOKEN"
```

### Response fields

<ResponseField name="id" type="string" required>
  The unique Top.gg-sourced Snowflake identifier for the project.
</ResponseField>

<ResponseField name="name" type="string" required>
  The project name as it appears on the external platform.
</ResponseField>

<ResponseField name="platform" type="string" required>
  The platform the project belongs to. One of `discord` or `roblox`.
</ResponseField>

<ResponseField name="type" type="string" required>
  The project type. One of `bot`, `server`, or `game`.
</ResponseField>

<ResponseField name="headline" type="string" required>
  The short description set during project creation.
</ResponseField>

<ResponseField name="tags" type="string[]" required>
  List of tag IDs associated with the project.
</ResponseField>

<ResponseField name="votes" type="number" required>
  Current vote count used for ranking calculations.
</ResponseField>

<ResponseField name="votes_total" type="number" required>
  Total all-time votes received by the project.
</ResponseField>

<ResponseField name="review_score" type="number" required>
  Average review score across all reviews.
</ResponseField>

<ResponseField name="review_count" type="number" required>
  Total number of reviews submitted for the project.
</ResponseField>

### Example response

```json theme={null}
{
  "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.

```bash theme={null}
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.

<ParamField body="headline" type="object">
  A map of locale codes to headline strings. Each headline must be between 3 and 140 characters.
</ParamField>

<ParamField body="page_content" type="object">
  A map of locale codes to page content strings (Markdown supported). Each entry must be between 300 and 50,000 characters.
</ParamField>

### 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.

<Info>
  Changes may take up to 1 hour to appear on the website due to caching.
</Info>

### Error responses

| Status | Description                                                                 |
| ------ | --------------------------------------------------------------------------- |
| `400`  | Invalid project token                                                       |
| `404`  | Project not found                                                           |
| `422`  | Validation error (unsupported locale, length violations, or missing fields) |

***

## POST /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.

<Note>
  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.
</Note>

```bash theme={null}
curl -X POST 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

<ParamField body="title" type="string" required>
  The announcement title. Must be between 3 and 100 characters.
</ParamField>

<ParamField body="content" type="string" required>
  The announcement body text. Must be between 10 and 2,000 characters.
</ParamField>

### Response fields

<ResponseField name="title" type="string" required>
  The title of the created announcement.
</ResponseField>

<ResponseField name="content" type="string" required>
  The body content of the created announcement.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp of when the announcement was created.
</ResponseField>

### Example response

```json theme={null}
{
  "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) |
| `429`  | Rate limited - only one announcement every 4 hours    |

***

## PATCH /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.

```bash theme={null}
curl -X PATCH 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](#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/@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.

```bash theme={null}
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

<ParamField body="data" type="object[]" required>
  The batch of metrics entries. Must contain between 1 and 100 entries.

  <Expandable title="Entry object properties">
    <ParamField name="metrics" type="object" required>
      The metrics payload for this entry. Must be a JSON object matching the project's platform shape. See [platform payloads](#platform-payloads).
    </ParamField>

    <ParamField name="timestamp" type="string">
      ISO 8601 timestamp of when the metrics were collected. Cannot be more than 5 minutes in the future. Entries without a timestamp are applied before dated entries, in the order they appear in the request.
    </ParamField>
  </Expandable>
</ParamField>

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

<ParamField body="server_count" type="integer">
  Total number of servers the bot is currently in. Must be zero or greater.
</ParamField>

<ParamField body="shard_count" type="integer">
  Total number of shards the bot is currently running. Must be zero or greater.
</ParamField>

```json theme={null}
{
  "server_count": 420,
  "shard_count": 67
}
```

### Discord server

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

<ParamField body="member_count" type="integer">
  Total number of members in the server. Must be zero or greater.
</ParamField>

<ParamField body="online_count" type="integer">
  Number of members currently online. Must be zero or greater and cannot exceed `member_count` when both are provided.
</ParamField>

```json theme={null}
{
  "member_count": 14820,
  "online_count": 3120
}
```

### Roblox game

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

<ParamField body="player_count" type="integer" required>
  Current number of players in the game. Must be zero or greater.
</ParamField>

```json theme={null}
{
  "player_count": 428
}
```

***

## PUT /projects/@me/commands

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.

```bash theme={null}
curl -X PUT 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](https://discord.com/developers/docs/interactions/application-commands#application-command-object). Pass an empty array to clear all commands.

<ParamField body="commands" type="object[]" required>
  Array of application command objects following Discord's application command structure.
</ParamField>

### Response

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