# Top.gg

## Docs

- [Bot Endpoints — Top.gg v0 API](https://docs.top.gg/api/v0/bots.md): Search bots, fetch individual bot details, retrieve voter lists, check vote status, read stats, and post server counts using the Top.gg v0 bot endpoints.
- [Top.gg Legacy v0 API Reference](https://docs.top.gg/api/v0/introduction.md): The Top.gg v0 legacy API provides bot and user endpoints at https://top.gg/api. New integrations should target v1. No Bearer prefix required.
- [User Endpoints — Top.gg v0 API](https://docs.top.gg/api/v0/users.md): Fetch a Top.gg user's public profile by their Discord user ID, including social links, roles, and avatar using the GET /users/:user_id endpoint.
- [Top.gg v1 REST API: Projects, Votes, Webhooks](https://docs.top.gg/api/v1/introduction.md): The Top.gg v1 REST API lets you fetch project data and track votes. Authenticate with a Bearer token. Errors follow RFC 7807 problem+json format.
- [REST API Endpoints for Projects](https://docs.top.gg/api/v1/projects.md): 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.
- [Track Votes with the Top.gg v1 API](https://docs.top.gg/api/v1/votes.md): Fetch paginated vote history with cursor-based pagination or check a specific user's vote status and expiry using the Top.gg v1 votes endpoints.
- [Webhooks API Reference for Top.gg v1](https://docs.top.gg/api/v1/webhooks.md): Top.gg v1 webhooks notify your server in real time using HMAC SHA-256 signatures. Supported scopes include vote.create and webhook.test.
- [Authenticate with the Top.gg API](https://docs.top.gg/authentication.md): Learn how to obtain your Top.gg API token from the dashboard, pass it in the Authorization header, and handle authentication errors for v0 and v1.
- [Top.gg Developer Documentation](https://docs.top.gg/introduction.md): Top.gg is a discovery platform for Discovery on the web. Use the REST API to post statistics, read votes, configure webhooks, and build integrations.
- [Top.gg .NET Library: DiscordBotsList.Api](https://docs.top.gg/libraries/dotnet.md): Use the DiscordBotsList.Api NuGet package to post bot stats, query bot and user data, and generate widgets from your .NET application.
- [Top.gg Go SDK: Community Library](https://docs.top.gg/libraries/go.md): A community-maintained Go library for the Top.gg API. Integrate Top.gg bot stats posting and vote tracking features into your Go Discord bot.
- [Top.gg Java SDK: Community Library](https://docs.top.gg/libraries/java.md): A community-maintained Java library for the Top.gg API. Post bot stats and retrieve bot and user information from your Java application.
- [Top.gg JavaScript SDK: Stats and Webhooks](https://docs.top.gg/libraries/javascript.md): Post bot stats and handle vote webhooks in Node.js using the official @top-gg/sdk npm package with AutoPoster and Express support.
- [Top.gg PHP SDK: Community Library](https://docs.top.gg/libraries/php.md): A community-maintained PHP library for the Top.gg API. Post bot stats, retrieve bot listings, and query user data from your PHP application.
- [Top.gg Python SDK: topggpy Library](https://docs.top.gg/libraries/python.md): Install topggpy to post bot stats, track votes, receive vote webhooks, and query the Top.gg API from your Python Discord bot application.
- [Top.gg Ruby SDK: Community Library](https://docs.top.gg/libraries/ruby.md): A community-maintained Ruby gem for the Top.gg API. Post bot stats, retrieve bot listings, and query Top.gg user data from your Ruby application.
- [Top.gg Rust SDK: Community Library](https://docs.top.gg/libraries/rust.md): A community-maintained Rust crate for the Top.gg API. Post bot stats, retrieve bot data, and query the Top.gg API from your Rust Discord bot.
- [Top.gg API Rate Limits and 429 Error Handling](https://docs.top.gg/resources/rate-limits.md): Understand Top.gg API rate limits: 100 requests per second globally and 60 per minute for bot endpoints, with 1-hour blocks on violations.
- [Webhook Event Reference for Top.gg](https://docs.top.gg/webhooks/events.md): Complete reference for all Top.gg webhook event types, their payload schemas, and example payloads for both v1 and legacy v0 webhooks.
- [Build Installable Top.gg Integrations](https://docs.top.gg/webhooks/integrations.md): Build approved integrations that let users connect your service to their Top.gg project with one click and receive webhook events automatically.
- [Receive Vote Notifications with Webhooks](https://docs.top.gg/webhooks/overview.md): Top.gg webhooks deliver real-time vote events to your server via HTTP POST requests, letting you reward voters instantly without polling the API.

## OpenAPI Specs

- [spec](https://top.gg/api/v1/openapi/spec.json)