Blist | The list of the best bots!

Get Bot Information ⫘

GET /api/v2/bot/:id/

Returns all information on a bot.

Response Body

JSON Property	Type	Description
name	String	The name of the target bot.
id	String	The ID of the target bot.
discriminator	String	The discriminator of the target bot.
main_owner	String	The ID of the target bots owner.
owners	String	The list of ID's of the target bots secondary owners.
library	String	The development library of the target bot.
website	String	The website link of the target bot.
github	String	The GitHub link of the target bot.
short_description	String	The short description of the target bot.
long_description	String	The long description of the target bot.
prefix	String	The command prefix of the target bot.
invite_url	String	The invite link of the target bot which may be a discord link or custom link.
support_server	String	The Discord support invite code of the target bot.
tags	Array<String>	The categories of the bot.
monthly_votes	Integer	The amount of votes the target bot has received in the current month.
total_votes	Integer	The amount of votes the target bot has received while on the list.
certified	Boolean	Whether the target bot is certified.
vanity_url	String	The target bots vanity url. This replaces the id in the url of a bots page.
server_count	Integer	The amount of servers the target bot is in.
shard_count	Integer	The amount of shard processes the target bot has.
added	Datetime	The time and date the target bot was listed.
invites	Integer	The amount of times the target bot has been invited through our list.
page_views	Integer	The amount of times the target bots page has been seen.
donate_url	String	The link to donate to the target bot.
avatar_url	String	The target bots avatar url on discord.
privacy_policy_url	String	The target bots privacy policy url.
status	String	The status of the target bot on discord (Updated every 30 minutes).
staff	Boolean	Whether the target bot is owned by a list staff member.
premium	Boolean	Whether the target bots owner paid for Blist premium.

{
  "name":"GiveawayBot",
  "id":"570338970261782559",
  "discriminator":"8109",
  "main_owner":"414713250832449536",
  "owners":"",
  "library":"discord.js",
  "website":"https://www.thegiveawaybot.com",
  "github":"",
  "short_description":"Manage your server's giveaways easily with GiveawayBot.",
  "long_description":"...",
  "prefix":"gb!",
  "invite_url":"https://discordapp.com/oauth2/authorize?client_id=570338970261782559&permissions=0&scope=bot",
  "support_server":"DGVVqR7",
  "tags":[
      "Utility"
  ],
  "monthly_votes":1,
  "total_votes":4,
  "certified":false,
  "vanity_url":"",
  "server_count":17921,
  "shard_count":20,
  "added":"2020-06-26T00:00:00Z",
  "invites":0,
  "page_views":13,
  "donate_url":"https://patreon.com/dieseljs",
  "avatar_url":"https://cdn.discordapp.com/avatars/570338970261782559/4466359a0c746451e655b439ad209c95",
  "privacy_policy_url":"",
  "status":"online",
  "staff":false,
  "premium":false
}

Get Server Information ⫘

GET /api/v2/server/:id/

Returns all information on a server.

Response Body

JSON Property	Type	Description
id	String	The ID of the target server.
main_owner	String	The ID of the target servers owner.
name	String	The name of the target server.
website	String	The website link of the target server.
short_description	String	The short description of the target server.
invite_url	String	The Discord invite code of the target server.
tags	Array<String>	The categories of the server.
monthly_votes	Integer	The amount of votes the target server has received in the current month.
total_votes	Integer	The amount of votes the target server has received while on the list.
vanity_url	String	The target servers vanity url. This replaces the id in the url of a servers page.
member_count	Integer	The amount of members the target server has.
added	Datetime	The time and date the target server was added.
joins	Integer	The amount of times the target server has been joined through our list.
page_views	Integer	The amount of times the target servers page has been seen.
donate_url	String	The link to donate to the target server.
card_background	String	The link to background of the servers card.
premium	Boolean	Whether the target servers owner paid for Blist premium.
icon_hash	Hash	The target servers icon on discord.
published	Boolean	Whether the target server is published.
archived	Boolean	Whether the target server has been archived by itself or its owner.

{
  "id":"423828791098605578",
  "main_owner":"150665783268212746",
  "name":"Sparklybot ✨",
  "website":"https://soheab.github.io/",
  "short_description":"This is the Official Support Server for Sparklybot ✨. But it isn't really focused on being that, instead there are allot of things to do!",
  "invite_url":"yCzcfju",
  "tags":
    [
      "Fun",
      "Meme",
      "Developer",
      "Emotes",
      "Support Server"
    ],
  "monthly_votes":1,
  "total_votes":1,
  "vanity_url":"",
  "member_count":87,
  "added":"2021-01-22T02:02:20.410354Z",
  "joins":0,
  "page_views":0,
  "donate_url":"",
  "card_background":"",
  "premium":false,
  "icon_hash":"3e5e0b66b600c00f17118238d351453b",
  "published":true,
  "archived":false
}

Get User Information ⫘

GET /api/v2/user/:id/

Returns all information on a user.

Response Body

JSON Property	Type	Description
id	String	The ID of the target user.
name	String	The name of the target user.
discriminator	String	The discriminator of the target user.
bio	String	The bio of the target user.
staff	Boolean	Whether the target user is a staff member.
administrator	Boolean	Whether the target user is an administrator.
developer	Boolean	Whether the target user is a bot developer.
certified_developer	Boolean	Whether the target user is a developer of a certified bot.
joined	Datetime	The time and date the target user first joined.
reddit	String	The Reddit link of the target user.
snapchat	String	The Snapchat link of the target user.
instagram	String	The Instagram link of the target user.
twitter	String	The Twitter link of the target user.
github	String	The GitHub link of the target user.
website	String	The website link of the target user.
avatar_url	String	The target users avatar url on discord.
bug_hunter	Boolean	Whether the target user is a Bug Hunter.
blacklisted	Boolean	Whether the target user has been blacklisted.
premium	Boolean	Whether the target user paid for Blist premium.
vanity_url	String	The target users vanity url. This replaces the id in the url of a users page.
last_login	Datetime	The last time the user had to use Discord OAuth to login.

{
  "id": "272442568275525634",
  "discriminator": "0001",
  "name": "markawes",
  "bio": "Father of 3, and a cat",
  "staff": true,
  "administrator": true,
  "developer": true,
  "certified_developer": true,
  "joined": "2020-11-08T23:58:20.444722Z",
  "reddit": "",
  "snapchat": "markawes",
  "instagram": "markawes",
  "twitter": "markawes",
  "github": "markawes",
  "website": "https://marksbot.mwserver.site",
  "avatar_url": "https://cdn.discordapp.com/avatars/272442568275525634/79d8cb0517126a18562b4b4d04275c01",
  "bug_hunter": true,
  "blacklisted": false,
  "premium": true,
  "vanity_url": "markawes",
  "last_login": "2021-01-08T22:39:46.213979Z"
}

Get User Bots ⫘

GET /api/v2/user/:id/bots/

Returns all information on a users bots.

Response Body

JSON Property	Type	Description
bots	Array	The list of bots the user has.

{
  "bots": 
    [
      {
        "id": "440176226338865167", 
        "main_owner": "150665783268212746", 
        "discriminator": "2325", 
        "name": "Sparklybot \u2728", 
        "owners": "679118121943957504 712737377524777001", 
        "library": "discord.py", 
        "website": "https://soheab.github.io/", 
        "github": "", 
        "short_description": "A bot completely made for fun! With Fun, Moderation and Memes + Extras!", "long_description": 
        "<style>\r\n\r\n.text-muted {\r\n    color: #495057;\r\n}\r\n\r\n.badge {\r\n    background-color: #495057;\r\n    color: white;\r\n    border-radius: 12px;\r\n}\r\n\r\nspan.badge.badge-pill.badge-secondary {\r\n    color: black;\r\n    background-color: white;\r\n}\r\n\r\na.badge.badge-black {\r\n    color: white;\r\n    background: black;\r\n}\r\n\r\na.btn.btn-secondary.btn-sm {\r\n    background-color: #ffd700;\r\n    color: black;\r\n}\r\na.btn.btn-info.btn-sm {\r\n    background-color: #7289da;\r\n}\r\n\r\na.btn.btn-warning.btn-sm {\r\n    background-color: #ef0c0c;\r\n}\r\n\r\n.pb-5, .py-5 {\r\n    padding-bottom: 2rem!important;\r\n}\r\n\r\n.mb-5, .my-5 {\r\n    margin-bottom: -3rem!important;\r\n}\r\n\r\nh6.text-muted.pl-5 {\r\n    color: darkorange;\r\n}\r\n\r\n.container.pt-5 h1 {\r\n    border-style: solid;\r\n    text-align: center;\r\n    line-height: 1;\r\n    padding: 1rem 0rem;\r\n    color: darkorange;\r\n    margin-bottom: revert;\r\n    margin-top: -40px;\r\n}\r\n\r\nh6.text-muted.pt-5 {\r\n    color: darkorange!important;\r\n    font-weight: 700;\r\n    border-style: solid;\r\n    margin-top: revert;\r\n    line-height: 1;\r\n    padding: 1rem 1rem 3rem;\r\n    text-align: center;\r\n}\r\n\r\n</style>\r\n\r\n<h3>Commands</h3>\r\n<p>There are <b>190+</b> commands. Showing them all here would too much. So... They can all be <a href=\"https://soheab.github.io/commands\">viewed here</a> in a very clean view! or a easy way is doing <b>s!help</b> in your server.  Also all the commands are case insensitive.</p>\r\n<br>\r\n<h3>Key features</h3>\r\n<p>\r\n1. My invite only includes the permissions the bot <b>really</b> needs, please don't give it any extra perms! \r\nand especially not admin.\r\n<br><br>\r\n► Case insensitive everything, commands and prefix so 100% mobile friendly.<br>\r\n► Every command is tested and selfmade so that it works is guaranteed. If a command doesn't, please report it and you can slap me.<br>\r\n► Abuse resistant, every command has the name of the author in it. And all commands have a cooldown of 5+ secs.<br>\r\n► Improves everyday! just see s!changelog.<br>\r\n► Many useless things but also things you do not often see in a bot.<br>\r\n► Friendly embeds, i love to put more info in less space but still let it look good. So you won't expect big spammy embed from this bot.<br>\r\n</p>\r\n<br>\r\n<h3>Updates</h3>\r\n<p>This bot gets better every day! Just check the <b>s!changelog</b> in there should be all the changes that happen to the bot. You can also suggest anything with: <b>s!suggest</b>! Anything that gets suggested has a very high chance to be added.</p>\r\n<br>\r\n<h3>Bugs</h3>\r\n<p>Please report any bug or mistake in grammar with the command: <b>s!report</b>! and it will be <b>100%</b> fixed in max a day!</p>\r\n<br>\r\n<h3>Support</h3>\r\n<p>If you need any help with anything such as inviting, giving perms, join my support server via the button above or via the **s!support** command.</p>", 
        "prefix": "s!, S!", 
        "invite_url": "https://discordapp.com/oauth2/authorize?client_id=440176226338865167&permissions=1543892055&scope=bot", 
        "support_server": "yCzcfju", 
        "tags": [
          "Moderation", 
          "Music", 
          "Meme", 
          "Utility"
        ], 
        "monthly_votes": 74, 
        "total_votes": 182, 
        "certified": true, 
        "vanity_url": "sparklybot", 
        "server_count": 366, 
        "shard_count": 0, 
        "added": "2020-06-23T00:00:00Z", 
        "invites": 0, 
        "page_views": 1179, 
        "donate_url": "", 
        "avatar_url": "https://cdn.discordapp.com/avatars/440176226338865167/3e5e0b66b600c00f17118238d351453b", 
        "privacy_policy_url": "https://soheab.github.io/privacy-policy", 
        "status": "online", 
        "staff": true, 
        "premium": true, 
        "archived": false
      }
    ]
}

Get User Servers ⫘

GET /api/v2/user/:id/servers/

Returns all information on a users servers.

Response Body

JSON Property	Type	Description
servers	Array	The list of servers the user has.

{
  "servers": 
    [
      {
        "id":"423828791098605578",
        "main_owner":"150665783268212746",
        "name":"Sparklybot ✨",
        "website":"https://soheab.github.io/",
        "short_description":"This is the Official Support Server for Sparklybot ✨. But it isn't really focused on being that, instead there are allot of things to do!",
        "invite_url":"yCzcfju",
        "tags":
          [
            "Fun",
            "Meme",
            "Developer",
            "Emotes",
            "Support Server"
          ],
        "monthly_votes":1,
        "total_votes":1,
        "vanity_url":"",
        "member_count":87,
        "added":"2021-01-22T02:02:20.410354Z",
        "joins":0,
        "page_views":0,
        "donate_url":"",
        "card_background":"",
        "premium":false,
        "icon_hash":"3e5e0b66b600c00f17118238d351453b",
        "published":true,
        "archived":false
      }
    ]
}

Get Bot Votes ⫘

GET /api/v2/bot/:id/votes/

Returns all votes on a bot in the last 12 hours. Requires Authorization.

Response Body

JSON Property	Type	Description
votes	Object<Array<Snowflake, Datetime>>	A vote for the target bot.

{
  "votes":
    [
      {
        "user":"679118121943957504",
        "time":"2020-11-30T02:21:20.519Z"
      }
    ]

Get Bot Announcements ⫘

GET /api/v2/bot/:id/announcements/

Returns all announcements on a bot.

Response Body

JSON Property	Type	Description
announcements	Object<Array<String, String, Boolean, DateTime>>	An announcement for the target bot.

{
  "announcements": [
    {
      "announcement": "<p><center><p><strong>SCHEDULED MAINTENANCE</strong></p>\n<p>There will be some hardware upgrades to the VPS that hosts the bot at <strong><font color=\"red\">15:00 on Friday, 15th January 2021 (UTC+0)</strong></font> this maintenance is expected to last 2 hours, there should be no downtime but it's always possible.</p></center></p>", 
      "author": "272442568275525634", 
      "pinned": true, 
      "time": "2021-01-09T21:09:26.207Z"
    }
  ]
}

Post bot announcement ⫘

POST /api/v2/bot/:id/announcements/

Creates an announcement about your bot. Requires Authorization.

Request Body

JSON Property	Type	Required	Description
announcements	String	Yes	The important announcement about your bot.
pinned	String	No	Whether the announcement should be pinned to the top of the bot page.

Delete bot announcement ⫘

DELETE /api/v2/bot/:id/announcements/

Deletes an announcement about your bot. Requires Authorization.

Request Body

JSON Property	Type	Required	Description
announcement_id	Integer	Yes	The announcement unique id. This can be found on the bottom of the announcement card.

Get Bot Reviews ⫘

GET /api/v2/bot/:id/reviews/

Returns all reviews on a bot.

Response Body

JSON Property	Type	Description
reviews	Object<Array<String, Boolean, Datetime>>	A review for the target bot.

"reviews":
  [
    {
      "feedback":"The bot is good, nice support staff and pretty simple to use bot. ",
      "recommended":true,
      "time":"2020-11-15T13:35:56.192Z"
    },
    {
      "feedback":"Good bot with a very nice and friendly owner!",
      "recommended":true,
      "time":"2020-11-25T01:02:13.617Z"
    }
  ]

Patch Bot Stats ⫘

PATCH /api/v2/bot/:id/stats/

Provides Blist with statistics on your bot (Server count and Shard Count).

Request Body

Path Parameters	Parameter Type	Required	Parameter Description
server_count	Integer	Yes *	The amount of servers the target bot is in.
shard_count	Integer	No	The amount of shard processes the target bot has.

* Value is required but will be ignored if 'shard_count' is posted.

Errors ⫘

All errors within the API will be returned as a JSON response (excluding 500's & 404's).

Response Body

JSON Property	Type	Description
detail	String	A short description of the error.

{
  "detail": "Not found."
}

Ratelimits ⫘

All errors within the API will be returned as a JSON response (excluding 500's & 404's).

Ratelimits

Route	Limit
/api/v2/	1 / 5s
/api/v2/bots/	1 / 1m
/api/v2/server/:id/	1 / 3s
/api/v2/bot/:id/	1 / 3s
/api/v2/bot/:id/announcements/	1 / 120s
/api/v2/bot/:id/stats/	1 / 120s
/api/v2/bot/:id/votes/	1 / 5s
/api/v2/bot/:id/reviews/	1 / 5s
/api/v2/user/:id/	1 / 3s
/api/v2/user/:id/bots/	1 / 10s
/api/v2/user/:id/servers/	1 / 10s

Webhooks ⫘

Webhooks are a good way to publicize votes for your bot. They can also help in the use of vote-locking commands. When a user votes for your bot, you will receive a POST request to the url specified in the bot settings. A sample response body is below. Request headers are sent with your bots API key in an Authorization header.

Response Body

JSON Property	Type	Description
user	String	The id of the user who voted.
time	Datetime	The time which the user voted.

{
  "user": "679118121943957504", 
  "time": "2021-01-14 14:37:22.903849"
}

API libraries have been made to make posting and fetching stats a breeze from your preferred language and bot library. These libraries may not be maintained by Blist staff and may not have full support. Do you want to have your own API wrapper to be listed here? Join our discord or email us at [email protected]
blist.py blist.javascript

blist.py - Python ⫘

GitHub PyPi

You'll want to make sure to check out the documentations table of contents for information on installing and getting the Blist API wrapper working correctly. You need to be using discord.py and be using the bot commands extension in your project to be able to use this API wrapper.

Example Usage

import blist
from discord.ext import commands

class BlistBotList(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        blist_api = blist.Blist(bot, token="your blist token") # Initialize a Blist instance

    @commands.command()
    async def post_server_count(self, ctx):
      await self.blist_api.post_bot_stats() # Posts your bots stats
      await ctx.send("Done!")

    @commands.command()
    async def botinfo(self, ctx, bot: discord.Member):
      if not bot.bot:
        return await ctx.send("This user is not a bot!")

      bot = await self.blist_api.fetch_bot(bot_id=bot.id) # Gets information on a bot user
      await ctx.send(bot)

def setup(bot):
  bot.add_cog(BlistBotList(bot))

blist.javascript - JavaScript ⫘

GitHub NPM

This API requires your bot to be using discord.js and a Discord.Client() instance. Make sure to check out the GitHub for full documentation.

Example Usage

// Import the blist.javascript package
const blist = require("blist.javascript");
const discordjs = require('discord.js');

const bot = new discordjs.Client();
// Create a new blist instance
const client = new blist(bot, apiKey);

// Fetch bot stats
client.fetchBot(id).then((bot) => console.log(bot));

// Fetch user stats
client.fetchUser(id).then((user) => console.log(user));

API Documentation

Get Bot Information ⫘

Get Server Information ⫘

Get User Information ⫘

Get User Bots ⫘

Get User Servers ⫘

Get Bot Votes ⫘

Get Bot Announcements ⫘

Post bot announcement ⫘

Delete bot announcement ⫘

Get Bot Reviews ⫘

Patch Bot Stats ⫘

Errors ⫘

Ratelimits ⫘

Webhooks ⫘

API Wrappers

blist.py - Python ⫘

Example Usage

blist.javascript - JavaScript ⫘

Example Usage