Already on top.gg? List here too

First things first: it's not either-or

Listing here doesn't replace your top.gg listing, and it doesn't have to. Both run side by side without conflict: separate page, separate votes, separate webhooks. What twenty minutes of work gets you is a second place where your bot's name can be found on Google, a server-count history fed by Discord's own App Directory numbers and, early on, the founding developer terms for the first people who list.

One thing worth stating plainly: your description, your images and your copy belong to you, no matter where they're currently published. You're free to use them here too.

Step 1: bring your description

Open your existing listing, copy your long description as Markdown and paste it into the submission form. Headings, lists and links work; raw HTML and scripts are stripped; we're stricter about that than most.

Two things are different here. First, there are two language versions, German and English. You don't have to maintain both: if one is missing, we show the other with a small note. A German version is worth the effort though, because German search terms are how a lot of visitors arrive in the first place. Second, the short description is capped at 160 characters and shows up on cards and in search results. One sentence that says what the bot does beats any feature list.

Step 2: import your commands instead of retyping them

Discord hands you your own command list as JSON. One request with your bot token, and the form takes the whole list, subcommands included. The exact call, with examples in eleven languages, is on the command import page. Nothing to retype.

Step 3: post your server count

After approval you get an API key in the dashboard. Your bot reports its server count with a single request:

POST https://topbot.gg/api/v1/bots/{application-id}/stats
Authorization: Bearer {api-key}
Content-Type: application/json

{ "serverCount": 1234 }

If your bot already posts stats to your existing listing, this is the same move with a different URL. The full API documentation has JavaScript and Python examples.

Independently of that, we fetch your server count from Discord's App Directory every day if your bot is listed there. It fills your visible server count for as long as you don't report one yourself; your own reports take precedence. The history chart on your bot page is opt-in and switched on in the dashboard.

Step 4: add a vote webhook next to the one you have

Vote rewards work the way you already know: you set a URL and a secret in the dashboard, and we POST on every vote. The signature is an HMAC-SHA256 over timestamp and body, failed deliveries are retried with growing backoff, and every attempt is visible in a delivery log, with a test button.

The payload isn't identical to what other directories send, but it's small and documented. In practice it's a second endpoint next to your existing vote handler, not a rewrite. Or skip code entirely and point it at a Discord channel webhook. Every vote then lands as an embed in your server.

Step 5: badge in the README

The dashboard has ready-made copy snippets for badges showing server count, votes or rating, as HTML and Markdown, working in both GitHub themes. There's also the server-history chart as an embeddable SVG widget for your website or README.

What doesn't carry over

We don't import votes, reviews or ranks from other platforms. The numbers here start at zero and are real in exchange. And every bot goes through a human review before it's published, usually within 72 hours. What gets checked is on the developer page.