Top.gg Documentation

Bots

API resource for a bots or apps on a platform like Discord


Bot endpoints are subject to stricter rate limits than others.

Search Bots

GET

/bots

Gets a list of bots that match a specific query.

Query String Parameters

FieldTypeDescriptionDefault
limitnumberThe amount of bots to return. Max. 50050
offsetnumberAmount of bots to skip0
searchstringA search string in the format of field: value field2: value2
sortstringThe field to sort by. Prefix with - to reverse the order
fieldsstringA comma separated list of fields to showAll fields

Response Fields

FieldTypeDescription
resultsBot[]The matching bots
limitnumberThe limit used
offsetnumberThe offset used
countnumberThe length of the results array
totalnumberThe total number of bots matching your search
/bots?search=Luca
{
  "results": [
    {
      "defAvatar": "6debd47ed13483642cf09e832ed0bc1b",
      "invite": "",
      "website": "https://discordbots.org",
      "support": "KYZsaFb",
      "github": "https://github.com/DiscordBotList/Luca",
      "longdesc": "Luca only works in the **Discord Bot List** server.    \r\nPrepend commands with the prefix `-` or `@Luca#1375`.    \r\n**Please refrain from using these commands in non testing channels.**\r\n- `botinfo @bot` Shows bot info, title redirects to site listing.\r\n- `bots @user`* Shows all bots of that user, includes bots in the queue.\r\n- `owner / -owners @bot`* Shows all owners of that bot.\r\n- `prefix @bot`* Shows the prefix of that bot.\r\n* Mobile friendly version exists. Just add `noembed` to the end of the command.\r\n",
      "shortdesc": "Luca is a bot for managing and informing members of the server",
      "prefix": "- or @Luca#1375",
      "lib": "discord.js",
      "clientid": "264811613708746752",
      "avatar": "7edcc4c6fbb0b23762455ca139f0e1c9",
      "id": "264811613708746752",
      "discriminator": "1375",
      "username": "Luca",
      "date": "2017-04-26T18:08:17.125Z",
      "server_count": 2,
      "guilds": ["417723229721853963", "264445053596991498"],
      "shards": [],
      "monthlyPoints": 19,
      "points": 397,
      "certifiedBot": false,
      "owners": ["129908908096487424"],
      "tags": ["Moderation", "Role Management", "Logging"],
      "donatebotguildid": ""
    }
  ],
  "limit": 1,
  "offset": 0,
  "count": 1,
  "total": 7
}

Find One Bot

GET

/bot/:bot_id

Finds a single bot

Example Response

Bot or 404

Last 1000 Votes

GET

/bots/:bot_id/votes

Gets the last 1000 voters for your bot.

If your bot receives more than 1000 votes monthly you cannot use this endpoints and must use webhooks and implement your own caching instead.

This example uses Luca but users are restricted to only receiving their own bots' votes. Replace the id with your own bot.

Example Response

/bots/1234/votes
[
  {
    "username": "Xetera",
    "discriminator": "0001",
    "id": "140862798832861184",
    "avatar": "a_1241439d430def25c100dd28add2d42f"
  }
]

Bot stats

GET

/bots/:bot_id/stats

Specific stats about a bot.

Response

FieldTypeDescription
server_count?numberThe amount of servers the bot is in
shardsstring[]The amount of servers the bot is in per shard. Always present but can be empty
shard_count?numberThe amount of shards a bot has

Individual User Vote

GET

/bots/:bot_id/check

Checking whether or not a user has voted for your bot. Safe to use even if you have over 1k monthly votes.

Params

FieldTypeDescription
userIdsnowflakeUser's Discord ID

Example Response

/bots/9876/check?userId=1234
{
  "voted": 1
}

Post Stats

POST

/bots/:bot_id/stats

Post Body

FieldTypeDescriptionRequired
server_countnumber | number[]Amount of servers the bot is in. If an Array, it acts like shards✔️
shardsnumber[]Amount of servers the bot is in per shard.
shard_idnumberThe zero-indexed id of the shard posting. Makes server_count set the shard specific server count.
shard_countnumberThe amount of shards the bot has.

Example Response

/bots/9876/check?userId=1234
{
  "voted": 1
}

Bot Structure

FieldTypeDescription
idstringThe id of the bot
usernamestringThe username of the bot
discriminatorstringThe discriminator of the bot
avatar?stringThe avatar hash of the bot's avatar
defAvatarstringThe cdn hash of the bot's avatar if the bot has none
libstringThe library of the bot
prefixstringThe prefix of the bot
shortdescstringThe short description of the bot
longdesc?stringThe long description of the bot. Can contain HTML and/or Markdown
tagsstring[]The tags of the bot
website?stringThe website url of the bot
support?stringThe support server invite code of the bot
github?stringThe link to the github repo of the bot
ownerssnowflake[]of Snowflakes The owners of the bot. First one in the array is the main owner
guildssnowflake[]of Snowflakes The guilds featured on the bot page
invite?stringThe custom bot invite url of the bot
datedatestringThe date when the bot was approved
certifiedBotbooleanThe certified status of the bot
vanity?stringThe vanity url of the bot
pointsnumberThe amount of upvotes the bot has
monthlyPonumbersnumberThe amount of upvotes the bot has this month
donatebotguildidstringThe guild id for the donatebot setup

Example Structure

{
  "defAvatar": "6debd47ed13483642cf09e832ed0bc1b",
  "invite": "",
  "website": "https://discordbots.org",
  "support": "KYZsaFb",
  "github": "https://github.com/DiscordBotList/Luca",
  "longdesc": "Luca only works in the **Discord Bot List** server.    \r\nPrepend commands with the prefix `-` or `@Luca#1375`.    \r\n**Please refrain from using these commands in non testing channels.**\r\n- `botinfo @bot` Shows bot info, title redirects to site listing.\r\n- `bots @user`* Shows all bots of that user, includes bots in the queue.\r\n- `owner / -owners @bot`* Shows all owners of that bot.\r\n- `prefix @bot`* Shows the prefix of that bot.\r\n* Mobile friendly version exists. Just add `noembed` to the end of the command.\r\n",
  "shortdesc": "Luca is a bot for managing and informing members of the server",
  "prefix": "- or @Luca#1375",
  "lib": "discord.js",
  "clientid": "264811613708746752",
  "avatar": "7edcc4c6fbb0b23762455ca139f0e1c9",
  "id": "264811613708746752",
  "discriminator": "1375",
  "username": "Luca",
  "date": "2017-04-26T18:08:17.125Z",
  "server_count": 2,
  "guilds": ["417723229721853963", "264445053596991498"],
  "shards": [],
  "monthlyPoints": 19,
  "points": 397,
  "certifiedBot": false,
  "owners": ["129908908096487424"],
  "tags": ["Moderation", "Role Management", "Logging"],
  "donatebotguildid": ""
}
Edit on GitHub