Guild List

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.

Auth required

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

POST /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.

Auth required Rate limited: once per 5 hours

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

Important: The 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

202 Accepted

{
  "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://bdtools.xyz/bot-guild-list"
}

400 Bad Request — Empty Body

{ "error": "Request body is empty." }

400 Bad Request — Missing Author ID

{ "error": "The first line must be \"Author ID: <id>\"." }

400 Bad Request — Empty Author ID

{ "error": "Author ID value is empty." }

400 Bad Request — No Servers

{ "error": "No server entries found after Author ID." }

400 Bad Request — Invalid Format

{ "error": "Invalid body format. Found 7 server lines — must be a multiple of 4 (Server Name, Server ID, Invite Link, Owner ID per server)." }

400 Bad Request — Wrong Field Order

{ "error": "Line 3: Expected \"Server ID:\", got \"Invite Link: ...\"" }

400 Bad Request — Empty Field

{ "error": "Server entry at index 2 has one or more empty fields." }

401 Unauthorized

{ "error": "Invalid or missing API key." }

403 Forbidden — Author ID Mismatch

{ "error": "Author ID does not match API key." }

405 Method Not Allowed

{ "error": "Method not allowed. Use POST." }

429 Too Many Requests

{
  "error": "You can only submit once every 5 hours.",
  "nextAllowed": "2026-04-30T17:00:00.000Z"
}

500 Internal Server Error — Database Connection

{ "error": "Database connection failed." }

500 Internal Server Error — Processing

{ "error": "Internal server error." }

GET /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://bdtools.xyz/bot-guild-list — it cannot be called directly from bots or external apps.

Auth required Redis cached

Responses

200 OK

{
  "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
  ]
}

401 Unauthorized

{ "error": "Invalid or missing API key." }

403 Forbidden — Invalid Origin

{ "error": "Access denied: Invalid origin." }

404 Not Found

{ "error": "No servers found for this API key." }

405 Method Not Allowed

{ "error": "Method not allowed. Use GET." }

500 Internal Server Error — Database Connection

{ "error": "Database connection failed." }

500 Internal Server Error — Query

{ "error": "Internal server error." }

Enriched Data: The response includes additional fields (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.

BDTools API Docs

Overview

Authentication

Rate Limits & Restrictions

Request Body

Responses

Example BDFD Command

Responses

BDTools API Docs

Confirm Logout

Guild List

Overview

Authentication

Rate Limits & Restrictions

Request Body

Responses

Example BDFD Command

Responses