Top.gg v1 REST API: Projects, Votes, Webhooks

The v1 API is the current recommended version of the Top.gg REST API. It provides endpoints for managing your project, retrieving vote data, and integrating webhooks. All new integrations should target v1.

Base URL

All v1 API requests are made to the following base URL:

https://top.gg/api/v1

Authentication

Authenticate every request by passing your Top.gg token as a Bearer token in the Authorization header. You can find your token in your project’s Integrations & API settings on Top.gg.

Authorization: Bearer $TOPGG_TOKEN

For example, a complete request looks like this:

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

Legacy tokens (without the Bearer prefix) are only valid on v0 endpoints. They will not authenticate against v1 endpoints.

Project routes and `@me`

Project endpoints are addressed by Top.gg project ID, for example GET /projects/:project_id/votes. Which form you use depends on your credential:

With an OAuth access token or an application token, always pass the explicit project ID of a project the credential covers.
With a project token, use @me in place of :project_id. The token itself identifies the project, and it only works with @me.

Request bodies and responses are identical for both forms.

Error handling

Error responses from the v1 API follow RFC 7807 and use the application/problem+json content type. Every error response includes the following fields:

type ProblemDetails = {
  type: string;       // A URI identifying the error type
  title: string;      // Short human-readable summary
  status: number;     // HTTP status code
  detail: string;     // Human-readable explanation of this specific occurrence
};

An example error response for a missing or invalid token looks like:

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The provided token is missing or invalid."
}

Use the status field to determine how to handle errors programmatically, and the detail field to surface a meaningful message when debugging.

​Base URL

​Authentication

​Project routes and @me

​Error handling

Base URL

Authentication

Project routes and `@me`

Error handling