API Documentation

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 Template Information


GET /api/v2/template/:code/

Returns all information on a template.


Response Body

JSON Property Type Description
main_owner String The ID of the target templates owner.
name String The name of the target template.
description String The description of the target template.
code String The Discord code of the template url.
tags Array<String> The categories of the template.
added Datetime The time and date the target template was added.
uses Integer The amount of times the target template has been used.
icon_url String The target templates icon url on discord.


{
  "main_owner":"679118121943957504",
  "code":"EB2VsaQ3cpPb",
  "name":"Bot List",
  "description":"Use this template to make your own list!",
  "added":"2021-02-03T14:19:07.365841Z",
  "tags":[
    "Science and Technology"
  ],
  "icon_url":"https://cdn.discordapp.com/icons/716445624517656727/a_199d1217d4c1fd90876c4917a8eb89da.gif",
  "uses":0
}

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 Wrappers



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));