API Documentation

BotBlock provides a single API endpoint that allows bot owners to quickly post their server/guild count to all bot lists that we have API data for.
This means the bot owners only ever have to make a single request to update their bot stats on all bot lists.

We have first and third-party libraries created for many major bot development languages that provide easy implementation of the BotBlock API. Check them out or use the documentation below to create your own implementation.

BotBlock does not store any user data at all. All data sent to this API is passed directly onto each list's API as necessary. Authorization tokens are not stored and are only shared with their respective list's API.

Update bot/guild count

POST /api/count
Content-Type: application/json
Request Body
JSON PropertyTypeRequiredDescription
server_countIntegerYes *The server/guild count for your bot.
bot_idSnowflakeYesThe ID of your bot.
shard_idIntegerNoThe shard ID for the current count being posted. **
shard_countIntegerNoThe total number of shards for the bot. **
shardsArray<Integer>NoThe server/guild count per shard. **
botlist.spaceStringNoYour Authorization token for botlist.space.
botsfordiscord.comStringNoYour Authorization token for botsfordiscord.com.
bots.ondiscord.xyzStringNoYour Authorization token for bots.ondiscord.xyz.
discordapps.devStringNoYour Authorization token for discordapps.dev.
discord.boatsStringNoYour Authorization token for discord.boats.
discordbots.orgStringNoYour Authorization token for discordbots.org.
discordbotlist.comStringNoYour Authorization token for discordbotlist.com.
discordbotreviews.xyzStringNoYour Authorization token for discordbotreviews.xyz.
discordbot.worldStringNoYour Authorization token for discordbot.world.
discord.bots.ggStringNoYour Authorization token for discord.bots.gg.
discordsbestbots.xyzStringNoYour Authorization token for discordsbestbots.xyz.
discordbots.funStringNoYour Authorization token for discordbots.fun.
divinediscordbots.comStringNoYour Authorization token for divinediscordbots.com.
lbots.orgStringNoYour Authorization token for lbots.org.
mythicalbots.xyzStringNoYour Authorization token for mythicalbots.xyz.
wonderbotlist.comStringNoYour Authorization token for wonderbotlist.com.
yabl.xyzStringNoYour Authorization token for yabl.xyz.

* Value is required but will be ignored if 'shards' is posted and the current list accepts a 'shards' value.
** This information is only passed on to bot lists who support it.
This table will automatically update when new bot lists with server count APIs are added to the list.

Response Body
JSON PropertyTypeDescription
successObject<Array<Integer, String, String>>All list IDs that successfully posted will be listed here. See below for contents.
failureObject<Array<Integer, String, String>>All list IDs that failed to post will be listed here. See below for contents.

In the success and failure objects, each list ID attempted will be a key with a value that is an array. The first item in the array is the HTTP status code of the response, the second is the string response body and the third item is the body data sent to the list.

Example Response
POST /api/count {"server_count": 200, "bot_id": "123456789012345678"}
{
    "success": {
        "thelist.org": [
            200,
            "{\"message\":\"OK\"}",
            "{\"server_count\":200}"
        ],
        "listofbots.com": [
            200,
            "",
            "{\"count\":200}"
        ]
    },
    "failure": {
        "brokenlist.co.uk": [
            500,
            "Bot not found",
            "{\"guilds\":200}"
        ]
    }
}

Get bot information from lists

GET /api/bots/:id
Response Body
JSON PropertyTypeDescription
idSnowflakeThe ID of the bot being fetched.
usernameStringThe username of the bot fetched. *
discriminatorStringThe discriminator of the bot fetched. *
ownersArray<Snowflake>The IDs of all known owners of the bot. *
server_countIntegerThe server/guild count for the bot. *
inviteStringThe invite URL for the bot (Discord or custom). *
list_dataObject<Array<Any, Integer>>Each list with a known bot GET API endpoint will have all its data returned along with the HTTP status code returned from the request under the key of the BotBlock ID for the list within the list_data property. See below for example.

* These values are calculated based on the most common response (max value for server/guild count, unique values for owners) from all lists' APIs that returned information on the bot being fetched. If no information is gathered these values may be blank.

Example Response
GET /api/bots/123456789012345678
{
    "id": "123456789012345678",
    "username": "My Bot",
    "discriminator": "1234",
    "owners": [
        "123456789012345678"
    ],
    "server_count": 500,
    "invite": "https://discordapp.com/oauth2/authorize?client_id=123456789012345678&scope=bot&permissions=8",
    "list_data": {
        "thelist.org": [
            <list data>,
            200
        ],
        "listofbots.com": [
            <list data>,
            200
        ],
        "brokenlist.co.uk": [
            <list data>,
            404
        ]
    }
}

Get all lists' API details

GET /api/lists
Query String Parameters
FieldTypeDescription
filterBooleanIf set to true, lists with no API data will not be included in the response.
Response Body
JSON PropertyTypeDescription
<list_id>ObjectThe ID used in BotBlock for the list acts as the key for each property in the response.
<list_id>api_docsStringThe URL stored for the API docs of the list.
<list_id>api_postStringThe URL stored for posting server/guild count to the list.
<list_id>api_fieldStringThe JSON field name for posting the server/guild count to the list.
<list_id>api_shard_idStringThe JSON field name for posting the current shard ID to the list.
<list_id>api_shard_countStringThe JSON field name for posting the bot shard count to the list.
<list_id>api_shardsStringThe JSON field name for posting an array of server counts per shard to the list.
<list_id>api_getStringThe URL stored for fetching bot information from the list.
Example Response
GET /api/lists
{
    "thelist.org": {
        "api_docs": "https://thelist.org/api/docs",
        "api_post": "https://thelist.org/api/bot/stats/:id",
        "api_field": "server_count",
        "api_shard_id": "shard_id",
        "api_shard_count": "shard_count",
        "api_shards": null,
        "api_get": "https://thelist.org/api/bot/info/:id"
    },
    "listofbots.com": {
        "api_docs": "https://listofbots.com/docs",
        "api_post": "https://listofbots.com/api/stats/:id",
        "api_field": "guild_count",
        "api_shard_id": null,
        "api_shard_count": null,
        "api_shards": "shards",
        "api_get": null
    }
}

Errors

All errors within the API will be returned as a JSON response. They will also have the appropriate HTTP status code set.

Response Body
JSON PropertyTypeDescription
errorBooleanThis will always be true to indicate an error was encountered.
statusIntegerThis will be the HTTP status code of the response and the error.
messageStringThis will contain the message explaining the error that was encountered.
Example Response
GET /api/helloworld
{
    "error": true,
    "status": 404,
    "message": "Endpoint not found"
}

Ratelimits

There is a global ratelimit on the BotBlock website per request source IP address of 10 requests every second.

This API has ratelimits in place based on request source IP address and, where possible, bot ID. This API may get ratelimited from lists if it is inundated with requests, therefore our ratelimits are high as to reduce the likelihood of this occurring.

The IP that BotBlock can see for your current connection is 18.206.13.39

Ratelimits
RouteRequest TypeLimit (requests / time period)per Bot ID
/api/countValid POST1 / 120sYes
/api/bots/:idGET1 / 30sNo
/api/listsGET1 / 1sNo
Response Body & Headers
HTTP Status: 429 Too Many Requests
JSON PropertyHTTP HeaderTypeDescription
retry_afterRetry-AfterIntegerHow many seconds until the API can be used again.
ratelimit_resetX-Rate-Limit-ResetIntegerHow unix timestamp when the API can be used again.
ratelimit_ipX-Rate-Limit-IPStringThe IP address that the API is ratelimiting in this response.
ratelimit_routeX-Rate-Limit-RouteStringThe API route that is being ratelimited in this response.
ratelimit_bot_idX-Rate-Limit-Bot-IDStringThe bot ID that the API is ratelimiting in this response.