Bot Endpoints

Note: The Bot endpoints are subject to stricter rate limits than others.

GET/bots

Search Bots

Gets a list of bots that match a specific query.

Query Parameters

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

Request

https://top.gg/api/bots

Response

{
  "results": [
    {
      "defAvatar": "6debd47ed13483642cf09e832ed0bc1b",
      "invite": "https://discord.com/oauth2/authorize?client_id=264811613708746752&scope=bot",
      "website": "https://top.gg",
      "support": "KYZsaFb",
      "github": "https://github.com/DiscordBotList/Luca",
      "longdesc": "Bot's long description",
      "shortdesc": "Bot's short description",
      "prefix": "- or @Luca#1375",
      "lib": "discord.js",
      "clientid": "264811613708746752",
      "avatar": "a7138418a83260e3331986619063ff78",
      "id": "264811613708746752",
      "discriminator": "1375",
      "username": "Luca",
      "date": "2017-04-26T18:08:17.125Z",
      "server_count": 2,
      "guilds": [],
      "shards": [],
      "monthlyPoints": 2,
      "points": 561,
      "certifiedBot": false,
      "owners": [],
      "tags": ["logging", "moderation", "role-management"],
      "bannerUrl": null,
      "donatebotguildid": null
    }
  ],
  "limit": 1,
  "offset": 0,
  "count": 1,
  "total": 7
}

GET/bots/:id

Find One Bot

Find a single bot by ID.

Request

https://top.gg/api/bots/:id

Response

{
  "defAvatar": "6debd47ed13483642cf09e832ed0bc1b",
  "invite": "https://discord.com/oauth2/authorize?client_id=264811613708746752&scope=bot",
  "website": "https://top.gg",
  "support": "KYZsaFb",
  "github": "https://github.com/DiscordBotList/Luca",
  "longdesc": "Bot's long description",
  "shortdesc": "Bot's short description",
  "prefix": "- or @Luca#1375",
  "lib": "discord.js",
  "clientid": "264811613708746752",
  "avatar": "a7138418a83260e3331986619063ff78",
  "id": "264811613708746752",
  "discriminator": "1375",
  "username": "Luca",
  "date": "2017-04-26T18:08:17.125Z",
  "server_count": 2,
  "guilds": [],
  "shards": [],
  "monthlyPoints": 2,
  "points": 561,
  "certifiedBot": false,
  "owners": [],
  "tags": ["logging", "moderation", "role-management"],
  "bannerUrl": null,
  "donatebotguildid": null
}

GET/bots/:id/votes

Last 1000 Votes

Gets the last 1000 voters within the past month 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.

Request

https://top.gg/api/bots/:id/votes

Response

[
  {
    "username": "Top.gg User",
    "id": "906879761811406848",
    "avatar": "024e6fbee0dd2e4bba8f462a02c0e705"
  }
]

GET/bots/:id/stats

Find Bot Stats

Get specific stats about a bot.

Request

https://top.gg/api/bots/:id/stats

Response

{
  "server_count": 2,
  "shards": [],
  "shard_count": 0
}

GET/bots/:id/check

Individual User Vote

Checking whether or not a user has voted for your bot.

If you are checking votes often, it is highly advised you use webhooks and store votes yourself - this prevents the command not working due to API rate-limits!

Query Parameters

Name
userId
Type
snowflake
Description
The user ID to check

Request

https://top.gg/api/bots/:id/check?userId=

Response

{
  "voted": 1
}

POST/bots/:id/stats

Post Stats

Post your bot's stats to the API.

Post Body

Name
server_count
Type
number | number[]
Description
The amount of servers your bot is in. If an Array, it acts like shards
Name
shards
Type
number[]
Description
Amount of servers the bot is in per shard. (Optional)
Name
shard_id
Type
number
Description
The zero-indexed id of the shard posting. Makes server_count set the shard specific server count. (Optional)
Name
shard_count
Type
number
Description
The amount of shards the bot has. (Optional)

Request

https://top.gg/api/bots/:id/stats

Response

{
  "voted": 1
}