Bots

Top.gg Documentation

Bot endpoints are subject to stricter rate limits than others.

Search Bots

Gets a list of bots that match a specific query.

Query String Parameters

Field	Type	Description	Default
limit	`number`	The amount of bots to return. Max. 500	50
offset	`number`	Amount of bots to skip	0
search	`string`	A search string in the format of `field: value field2: value2`
sort	`string`	The field to sort by. Prefix with - to reverse the order
fields	`string`	A comma separated list of fields to show	All fields

Response Fields

Field	Type	Description
results	`Bot[]`	The matching bots
limit	`number`	The limit used
offset	`number`	The offset used
count	`number`	The length of the results array
total	`number`	The 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

Finds a single bot

Example Response

Bot or 404

Last 1000 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 endpoint only returns unique votes, it does not include double votes (weekend votes).

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",
    "id": "140862798832861184",
    "avatar": "a_1241439d430def25c100dd28add2d42f"
  }
]

Bot stats

Specific stats about a bot.

Response

Field	Type	Description
server_count?	`number`	The amount of servers the bot is in
shards	`string[]`	The amount of servers the bot is in per shard. Always present but can be empty
shard_count?	`number`	The amount of shards a bot has

Individual User Vote

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

Params

Field	Type	Description
userId	`snowflake`	User's Discord ID

Example Response

/bots/9876/check?userId=1234

{
  "voted": 1
}

Post Stats

Post Body

Field	Type	Description	Required
server_count	`number` \| `number[]`	Amount of servers the bot is in. If an Array, it acts like shards	✔️
shards	`number[]`	Amount of servers the bot is in per shard.	❌
shard_id	`number`	The zero-indexed id of the shard posting. Makes server_count set the shard specific server count.	❌
shard_count	`number`	The amount of shards the bot has.	❌

Bot Structure

Field	Type	Description
id	`string`	The id of the bot
username	`string`	The username of the bot
discriminator	`string`	The discriminator of the bot
avatar?	`string`	The avatar hash of the bot's avatar
defAvatar	`string`	The cdn hash of the bot's avatar if the bot has none
lib	`string`	The library of the bot
prefix	`string`	The prefix of the bot
shortdesc	`string`	The short description of the bot
longdesc?	`string`	The long description of the bot. Can contain HTML and/or Markdown
tags	`string[]`	The tags of the bot
website?	`string`	The website url of the bot
support?	`string`	The support server invite code of the bot
github?	`string`	The link to the github repo of the bot
owners	`snowflake[]`	of Snowflakes The owners of the bot. First one in the array is the main owner
guilds	`snowflake[]`	of Snowflakes The guilds featured on the bot page
invite?	`string`	The custom bot invite url of the bot
date	`datestring`	The date when the bot was approved
server_count?	`number`	The amount of servers the bot has according to posted stats.
shard_count?	`number`	The amount of shards the bot has according to posted stats.
certifiedBot	`boolean`	The certified status of the bot
vanity?	`string`	The vanity url of the bot
points	`number`	The amount of upvotes the bot has
monthlyPoints	`number`	The amount of upvotes the bot has this month
donatebotguildid	`string`	The 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,
  "shard_count": 1,
  "guilds": ["417723229721853963", "264445053596991498"],
  "shards": [],
  "monthlyPoints": 19,
  "points": 397,
  "certifiedBot": false,
  "owners": ["129908908096487424"],
  "tags": ["Moderation", "Role Management", "Logging"],
  "donatebotguildid": ""
}

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

Search Bots

GET

Query String Parameters

Response Fields

Find One Bot

GET

Example Response

Last 1000 Votes

GET

Example Response

Bot stats

GET

Response

Individual User Vote

GET

Params

Example Response

Post Stats

POST

Post Body

Bot Structure

Example Structure

Edit on GitHub