Introduction

These developer pages document how to use our API to help you create and grow awesome bots for your community!

Getting Help

If you need some help or think you have spotted a problem with our API you can talk to us in our #api channel in our discord server. In the server you can ask questions about our official API Libraries or general queries about the API.

API Reference

Our API is a HTTPS/REST for general operations such as sending POST requests and receiving GET requests

Base URL
https://discordbots.org/api

Authentication

Currently to access certain aspects of our API you need to authorize yourself, this can be done by using your discord bot list token. Your token can be obtained from the My Bots page.

Authentication is performed with the Authorization HTTP header in the format Authorization: TOKEN

Example Authorization Header
Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjI2NDgxMTYxMzcwODc0Njc1MiIsImJvdCI6dHJ1ZSwiaWF0IjoxNDgzMDk5MjAwfQ.8tpNASxdSsfkVF7YparhyV1Ouy5ORQ3AM2jitd_Y-PI

API Libraries

JavaScript Library Usage

Java Library Usage

Python Library Usage

Unofficial Libraries

We currently don't endorse any unofficial libraries for the API, but if you think you could contribute to our current libraries check out our github repos and maybe submit a PR. If you think we should endorse your unofficial library for a language we don't already support hit us up at [email protected] or DM a Website Administrator

JavaScript Library

This is our official JavaScript Library for discordbots.org, if you have any issues please submit an issue on our github.

Installation

npm install dblapi.js

Usage

Basic example of posting a servercount to our API manually

const Discord = require("discord.js");
const client = new Discord.Client();
const DBL = require("dblapi.js");
const dbl = new DBL('Your discordbots.org token');

client.on('ready', () => {
    setInterval(() => {
        dbl.postStats(client.guilds.size);
    }, 1800000);
});
      

Automagically posting your server count to our API with Discord.js/Eris

const Discord = require("discord.js");
const client = new Discord.Client();
const DBL = require("dblapi.js");
const dbl = new DBL('Your discordbots.org token', client);

Posting Stats

To post server count and shard counts you use the postStats function, it takes 3 parameters. serverCount,shardId,shardCount

An example of posting shard counts

client.on('ready', () => {
    setInterval(() => {
        dbl.postStats(client.guilds.size, client.shards.Id, client.shards.total);
    }, 1800000);
});

Getting Stats

The function to get stats of a bot is getStats and only takes one parameter called id it can be used like this

dbl.getStats("378926376910192640")
and it will return a promise in the following format
{"server_count":642,"shards":[]}

Getting Votes

The function getVotes can be used to get information about which users have voted for your bot, it has one parameter of onlyids. An example using only IDs would be...

dbl.getVotes(true)
this will return an array of IDs because the boolean is set to true.

Checking a user has voted

This function hasVoted can be used to check if a user id has voted. It has one parameter being id. An example of checking if a user has voted.

dbl.hasVoted("129908908096487424")

Java Library

This is our official Java Library for discordbots.org, if you have any issues/bugs please submit an issue on our github.

Usage

First, build a DiscordBotListAPI object.

DiscordBotListAPI api = new DiscordBotListAPI.Builder()
                                             .token("token")
                                             .build();

Posting Stats

We provide three ways of post your stats to the website

#1 Post the server count for your whole bot

String botId = ...; // your bots ID
int serverCount = ...; // the total amount of servers across all shards

api.setStats(botId, serverCount);

#2 Post the server count for an individual shard

String botId = ...; // your bots ID
int serverCount = ...; // the server count of this shard
int shardId = ...; // the id of this shard
int shardCount = ...; // the amount of shards

api.setStats(botId, serverCount, shardId, shardCount);

#3 Post the server count every shard in one request

String botId = ...; // your bots ID
List<Integer> shardServerCounts = ...; // a list of all the shards' server counts

api.setStats(botId, shardServerCounts);  
        

Retrieving voters

You can either get the full objects or a simple list of the user IDs.

// will return the full User objects
List<User> voters = api.getVoters("bot id"); 

// will return a list of the user IDs
List<String> voterIds = api.getVoterIds("bot id");
        

Unofficial Libraries

We currently don't endorse any unofficial libraries for the API, but if you think you could contribute to our current libraries check out our github repos and maybe submit a PR. If you think we should endorse your unofficial library for a language we don't already support hit us up at [email protected] or DM a Website Administrator

Python Library

This is our official Python Library for discordbots.org, if you have any issues please submit an issue on our github. For full documentation please visit this link

Installation

Install via pip (recommended)

pip install dblpy

Install from source

git clone https://github.com/DiscordBotList/DBL-Python-Library
cd DBL-Python-Library
pip install -R requirements.txt

Example

import dblpy
from dblpy import Client
import asyncio
import aiohttp
import json

dbl = dblpy.Client()

botid = 264811613708746752  # your bots user id (client id on newer bots)
token = 'abcxyz'            # DBL Bot Token. Obtainable from https://discordbots.org/api

class Example:
    def __init__(bot):
        bot = bot
        session = aiohttp.ClientSession(loop=bot.loop)

    async def poststats():
        await dblpy.post_server_count(botid, dbltoken, 65)

    async def getstats():
        resp = await dblpy.get_server_count(botid)
        print(json.dumps(resp))

Unofficial Libraries

We currently don't endorse any unofficial libraries for the API, but if you think you could contribute to our current libraries check out our github repos and maybe submit a PR. If you think we should endorse your unofficial library for a language we don't already support hit us up at [email protected] or DM a Website Administrator

User Object

User Structure
Field Type Description
id Snowflake The id of the user
username String The username of the user
discriminator String The discriminator of the user
avatar? String The avatar hash of the user's avatar
defAvatar String The cdn hash of the user's avatar if the user has none
bio? String The bio of the user
banner? String The banner image url of the user
social Object The social usernames of the user
social.youtube? String The youtube channel id of the user
social.reddit? String The reddit username of the user
social.twitter? String The twitter username of the user
social.instagram? String The instagram username of the user
social.github? String The github username of the user
color? String The custom hex color of the user
supporter Boolean The supporter status of the user
certifiedDev Boolean The certified status of the user
mod Boolean The mod status of the user
webMod Boolean The website moderator status of the user
admin Boolean The admin status of the user

Get User

Use this endpoint to gain information about a particular user

GET/users/{user.id}

Bot Object

Bot Structure
Field Type Description
id Snowflake 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 Array of Strings 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 Array of Snowflakes The owners of the bot. First one in the array is the main owner
invite? String The custom bot invite url of the bot
date Date The date when the bot was approved
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

Get Bots

Use this endpoint to gain information about different bots

GET/bots
Query String Params
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 Array of bot objects 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

Get Bot

Use this endpoint to gain information about a specific bot

GET/bots/{bot.id}

Get Bot's Votes

Requires authentication.

Use this endpoint to see who have upvoted your bot

GET/bots/{bot.id}/votes
Query String Params
Field Type Description Default
onlyids Boolean Whether to return an array of simple user objects or an array of ids false
days Number Limits the votes to ones done within the amount of days you specify. (limit 0-31)

Get Bot's Stats

Use this endpoint to gain information about a specific bot's stats

GET/bots/{bot.id}/stats
Response fields
Field Type Description
server_count? Number The amount of servers the bot is in
shards Array 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

Post Bot's Stats

Requires authentication

Use this endpoint to post your bot's stats

POST/bots/{bot.id?}/stats
JSON Params
Field Type Description Required
server_count Number or Array of Numbers The amount of servers the bot is in. If an Array it acts like shards Yes (or shards)
shards Array of Numbers The amount of servers the bot is in per shard. No (unless server_count is not set)
shard_id Number The zero-indexed id of the shard posting. Makes server_count set the shard specific server count No
shard_count Number The amount of shards the bot has No

Widgets

Widgets are images that can display your bots stats on your own website! On this page we will tell you how to access and customise them.

Usage

To use the widget, you can insert the following link as an image into your website / documentation.

https://discordbots.org/api/widget/:ID.svg

Preview

In this example we use .svg but it can also be a .png. We recommend SVG for the best quality. That is an example of the large widget. There are also 5 small widgets which can be generated by editing the URL an example of a small widget is this

https://discordbots.org/api/widget/owner/:ID.svg

Preview

The /owner/ can be replaced with the following to get the 4 other smaller widgets: status,upvotes,servers and lib. You can also append a querystring to hide the avatar on the smaller widgets: ?noavatar=true

Preview

Customization

The current sections of the widget available for customization are as follows

Widget Querystring Paramters
Parameter Large Widget Small Widget Value
topcolor Hexadecimal
middlecolor Hexadecimal
usernamecolor Hexadecimal
certifiedcolor Hexadecimal
datacolor Hexadecimal
labelcolor Hexadecimal
highlightcolor Hexadecimal
avatarbg Hexadecimal
leftcolor Hexadecimal
rightcolor Hexadecimal
lefttextcolor Hexadecimal
righttextcolor Hexadecimal

Example of Customization

This is an example of changing the colors of the large widget

https://discordbots.org/api/widget/304789135124594698.svg?usernamecolor=FFFFFF&topcolor=000000

This is a preview of the examples output.

Rate Limits

The HTTP API implements a process for limiting and preventing spam requests. API users that regularly hit and ignore the limit will be blocked from our platform. These rate limits are in place to help prevent the abuse and overload of our services.

Rate limits are applied globally on all routes

Rate Limits
Route Request Type Requests Allowed Per Minute Punishment if Exceeded
/bots/* ANY 60 1 Hour Block

Exceeding a Rate Limit

If you exceed the set rate limit for the API you will receive a HTTP 429 and be blocked from posting to the API for one hour.

Rate Limit Response Structure
Field Type Description
retry-after integer Indicates how long the timeout period is/when you will be able to send requests again

Votes

Users can currently vote every 24 hours for each bot, in the API you can see who has voted in X month, X day and all time. By accessing the voting endpoint(s) you agree to the following.

Our current Rules on using our voting API.

What is currently not allowed:

  • Locking the majority of your bot until the user has voted for your bot

What we prefer developers do:

  • Give users rewards for voting
  • Try to limit voting required commands to 2-3

Consequences of breaking these rules:

  • First Offence - A stern warning from one of our beautiful moderators and possible reverting of bot votes.
  • Second Offence - If you haven't changed your ways after your first offence, or you are caught breaking these rules a second time, we will lock your access to the voting endpoint(s) and reset your votes.

We reserve the right to not follow these consequences in the exact order they are laid out here and take action how we see fit dependant on the scenario

My Bots

Here are your bots. You can view your API key here and other neat things!

C# / .NET Library

This is our official .NET Library for discordbots.org, if you have any issues please submit an issue on our github.

Installation

Nuget

If you're using Nuget you can use find it with the ID DiscordBotsList.Api or use

Install-Package DiscordBotsList.Api

Usage

Unauthorized API Usage

Setting Up

DiscordBotListApi DblApi = new DiscordBotListApi();

Getting Bots

//                            discord id
IBot bot = DblApi.GetBotAsync(160105994217586689);

Getting Users

//                              discord id
IUser bot = DblApi.GetUserAsync(121919449996460033);

Authorized API Usage

Setting Up

AuthDiscordBotListApi DblApi = new AuthDiscordBotListApi(BOT_DISCORD_ID, YOUR_TOKEN);

Updating Stats

ISelfBot me = await DblApi.GetMeAsync();
// Update stats sharded   indexShard shardCount shards
await me.UpdateStatsAsync(24,        50,        new[] { 12, 421, 62, 241, 524, 534 });

// Update stats           guildCount
await me.UpdateStatsAsync(2133);

Widgets

string widgetUrl = new SmallWidgetOptions()
	.SetType(WidgetType.OWNER)
	.SetLeftColor(255, 255, 255);
	.Build(160105994217586689);

Generates the following:

Unofficial Libraries

We currently don't endorse any unofficial libraries for the API, but if you think you could contribute to our current libraries check out our github repos and maybe submit a PR. If you think we should endorse your unofficial library for a language we don't already support hit us up at [email protected] or DM a Website Administrator

Webhooks

Instead of requesting our API to see the users who have voted for your bot, we now have webhooks! Webhooks will send a post request to a URL of your choice when your bot has been voted for.

Getting Started

Start by setting up your webhook URL in the edit form of your bot on this site, it can be found at https://discordbots.org/bot/:ID/edit once you have entered the URL you want the webhook to be sent to, you're all set! If you need help setting up webhooks inside of your bot don't be afraid to ask in our discord server in our #api channel.

Data Format

The format of the data your webhook URL will receive in a POST request

JSON Params
Field Type Description
bot Snowflake ID of the bot that received a vote
user Snowflake ID of the user who voted
type String The type of the vote (either "upvote" or "none", none means unvoting)