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:
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.
For example, a complete request looks like this:
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:
An example error response for a missing or invalid token looks like:
Use the status field to determine how to handle errors programmatically, and the detail field to surface a meaningful message when debugging. 
