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

To access 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

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.

Java Library

Usage

Please refer to the github docs

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

Go Library

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

Usage

Please refer to the github docs

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

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 Last 1000 Votes

IF YOU HAVE OVER 1000 VOTES PER MONTH YOU HAVE TO USE THE WEBHOOKS AND CAN NOT USE THIS

Use this endpoint to see who have upvoted your bot

GET/bots/{bot.id?}/votes

returnsAn Array of simple user objects

Individual User Id Voting Check for the past 24 hours.

Use this endpoint to see who have upvoted your bot in the past 24 hours. It is safe to use this even if you have over 1k votes.

GET/bots/{bot.id?}/check

Query String Params

Field

Type

Description

userId

Number

User id of the discord user

returns{voted: 1} or {voted: 0}

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

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

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

IF YOU HAVE OVER 1000 VOTES PER MONTH YOU HAVE TO USE THE WEBHOOKS

Votes

Users can currently vote every 24 hours for each bot. The /votes endpoint for your bot (the one you use via getVotes) only indexes the last 1000 votes. Please implement the webhook instead if you plan to process over 1000 votes.

Our current Rules on using our voting API.

Unacceptable use of our API (breaking these rules will result in appropriate punishments):

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

Voting Multiplier

To help give all bots a better chance to fight for the top spots we are now introducing vote multipliers. Votes count double on the weekend! On Fridays, Saturdays and Sundays, users votes count as two votes each.

Checking if the multiplier is live

Use this endpoint to find out if the multiplier is live so you can increase your bot's voting rewards for the weekend

GET/weekend

Example Response

{is_weekend: true}

Returns in JSON form a bool for the key is_weekend

My Bots

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

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.

Verifying the request

On the edit page you can see another input for "Authorization". Here you shall provide a "password" that you can check for.

To verify requests are coming from us, look for the value in the Authorization header and make sure it is the same as the value you provided in the form.

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 (should always be "upvote" except when using the test button it's "test")

isWeekend

Boolean

Whether the weekend multiplier is in effect, meaning users votes count as two

query?

String

Query string params found on the /bot/:ID/vote page. Example: ?a=1&b=2