Overview
The Guild List API allows bot developers to submit their bot's server list to BDTools and retrieve it for display on the Bot Guild List website. All endpoints require authentication via your API key.
Authentication
Include your API key in the
Authorization
header as a Bearer token with the
BDTools-
prefix:
// Authorization header format Authorization: Bearer BDTools-YOUR_API_KEY_HERE
Rate Limits & Restrictions
- ▸ POST /submit-server is rate limited to once per 5 hours per API key.
- ▸ GET /get-servers is only accessible from bdtools.xyz origin.
- ▸ Retrieved data is cached in Redis and invalidates on new submission.
// Base URL for all guild list endpoints https://api.bdtools.xyz
/submit-server
Submit your bot's guild list to BDTools. The request body must be plain text with a specific format. Processing happens asynchronously and may take 15 seconds to 5 minutes depending on server count and Discord API response times.
Headers
| Header | Value |
|---|---|
| Authorization |
Bearer BDTools-YOUR_API_KEY
|
Request Body
The body must be plain text (not JSON) with the following format. Each server requires exactly 4 lines in order:
Author ID: 123456789012345678 Server Name: My Awesome Server Server ID: 987654321098765432 Invite Link: https://discord.gg/abc123 Owner ID: 111222333444555666 Server Name: Another Cool Server Server ID: 555666777888999000 Invite Link: https://discord.gg/xyz789 Owner ID: 999888777666555444 // ... repeat for each server
Author ID
in the body must match the Discord user ID associated with
your API key, or the request will be rejected with a 403
error.
Responses
{ "message": "Processing started. This may take anywhere from 15 seconds to 5 minutes depending on the number of servers and Discord's response time.", "receivedServers": 42, "info": "Once processing is complete, you can view the updated guild list at https://app.bdtools.xyz/bot-guild-list" }
{ "error": "Request body is empty." }
{ "error": "The first line must be \"Author ID: <id>\"." }
{ "error": "Author ID value is empty." }
{ "error": "No server entries found after Author ID." }
{ "error": "Invalid body format. Found 7 server lines — must be a multiple of 4 (Server Name, Server ID, Invite Link, Owner ID per server)." }
{ "error": "Line 3: Expected \"Server ID:\", got \"Invite Link: ...\"" }
{ "error": "Server entry at index 2 has one or more empty fields." }
{ "error": "Invalid or missing API key." }
{ "error": "Author ID does not match API key." }
{ "error": "Method not allowed. Use POST." }
{ "error": "You can only submit once every 5 hours.", "nextAllowed": "2026-04-30T17:00:00.000Z" }
{ "error": "Database connection failed." }
{ "error": "Internal server error." }
Paste this into a BDFD command to automatically submit your bot's guild list. Full credit for the example code goes to Catearo.
$nomention $c[You have to change these two placeholder values] $var[count;NUMBER_OF_SERVERS] $httpAddHeader[Authorization;Bearer YOUR_API_KEY_HERE] $c[DO NOT CHANGE ANYTHING FROM THIS POINT ONWARDS] $var[i;1] $textSplit[$serverNames[$var[count];%%%];%%%] $httpPost[https://api.bdtools.xyz/submit-server; Author ID: $authorID $eval[$replaceText[$cropText[$repeatMessage[10;$repeatMessage[10;$repeatMessage[5;a]]];$min[$getTextSplitLength;250]];a;Server Name: %{DOL}%splitText[%{DOL}%var[i\]\] Server ID: %{DOL}%guildID[%{DOL}%splitText[%{DOL}%var[i\]\]\] Invite Link: %{DOL}%try %{DOL}%getServerInvite[%{DOL}%guildID[%{DOL}%splitText[%{DOL}%var[i\]\]\]\] %{DOL}%catch failed %{DOL}%endtry Owner ID: %{DOL}%serverOwner[%{DOL}%guildID[%{DOL}%splitText[%{DOL}%var[i\]\]\]\] %{DOL}%var[i\;%{DOL}%sum[1\;%{DOL}%var[i\]\]\] ]] ] $c[You can edit this message below:] $httpResult
YOUR_API_KEY_HERE
with your BDTools API key. Get your key at
api.bdtools.xyz
by signing in with Discord. The key expires every 30 days,
visit api.bdtools.xyz to refresh it.
/get-servers
Retrieve the stored guild list for your bot. This endpoint is
restricted to requests originating from
bdtools.xyz
and returns cached data from Redis. The cache is automatically
invalidated when you submit a new guild list.
Origin Restricted
This endpoint is only accessible from the Bot Guild List website at https://app.bdtools.xyz/bot-guild-list — it cannot be called directly from bots or external apps.
Responses
{ "authorId": "123456789012345678", "servers": [ { "name": "My Awesome Server", "id": "987654321098765432", "invite": "https://discord.gg/abc123", "ownerId": "111222333444555666", "memberCount": 1523, "icon": "https://cdn.discordapp.com/icons/987654321098765432/a_1234567890abcdef.png", "banner": "https://cdn.discordapp.com/banners/987654321098765432/fedcba0987654321.png", "description": "A community for awesome people", "features": ["COMMUNITY", "VERIFIED", "PARTNERED"], "vanityUrlCode": "awesome" }, { "name": "Another Cool Server", "id": "555666777888999000", "invite": "https://discord.gg/xyz789", "ownerId": "999888777666555444", "memberCount": 842, "icon": "https://cdn.discordapp.com/icons/555666777888999000/b_abcdef1234567890.png", "banner": null, "description": null, "features": [], "vanityUrlCode": null } // ... more servers ] }
{ "error": "Invalid or missing API key." }
{ "error": "Access denied: Invalid origin." }
{ "error": "No servers found for this API key." }
{ "error": "Method not allowed. Use GET." }
{ "error": "Database connection failed." }
{ "error": "Internal server error." }
memberCount, icon,
banner,
description,
features,
vanityUrlCode)
that are fetched asynchronously from Discord after submission.
These fields may be
null if
enrichment hasn't completed yet or if the data is unavailable.