Dlist.Space API

Welcome to the Dlist.Space API. This REST API lets you fetch bot data, manage votes, post reviews, post bot stats, and receive vote webhooks programmatically.

Base URL

https://api.dlist.space

Authentication

Some endpoints require a logged-in session via Discord OAuth2. Navigate to https://api.dlist.space/login to authenticate. The session is stored as a cookie.

PublicNo authentication required

API Tokens

Bot owners can generate an API token from their bot's edit page under the Token tab. Tokens are used to post stats (server count, user count, shard count) to our API.

Post Bot Stats

POST /api/bot/:id/stats
Authorization: Bearer YOUR_BOT_TOKEN

{
  "server_count": 1500,
  "user_count": 75000,
  "shard_count": 4
}

Rate Limits

To ensure fair usage and platform stability, the API enforces rate limits. Exceeding these will result in a 429 Too Many Requests response.

Public Endpoints

60 req / min

Authenticated

120 req / min

Voting

1 vote / 12 hrs

Endpoints

Webhooks

Configure a webhook URL and secret key in your bot's edit page. Whenever someone votes for your bot, we'll send a POST request to your URL.

Incoming Request

POST https://your-server.com/webhook
Content-Type: application/json
Authorization: YOUR_WEBHOOK_SECRET

{
  "user_id": "123456789012345678",
  "username": "CoolUser",
  "avatar": "https://cdn.discordapp.com/avatars/..."
}

Always validate the Authorization header matches your webhook secret before processing.

Handling Webhooks

Node.js (Express) — Handle vote webhook

const express = require("express");
const app = express();
app.use(express.json());

const WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET";

app.post("/webhook", (req, res) => {
  // 1. Validate the secret
  if (req.headers.authorization !== WEBHOOK_SECRET) {
    return res.status(401).json({ error: "Unauthorized" });
  }

  const { user_id, username } = req.body;
  console.log(`${username} (ID: ${user_id}) voted!`);

  // 2. Reward the user in your bot
  // e.g. giveCoins(user_id, 100);

  res.status(200).json({ ok: true });
});

app.listen(3000);

Python (Flask) — Handle vote webhook

from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET"

@app.route("/webhook", methods=["POST"])
def vote_webhook():
    # 1. Validate the secret
    if request.headers.get("Authorization") != WEBHOOK_SECRET:
        return jsonify({"error": "Unauthorized"}), 401

    data = request.get_json()
    user_id = data.get("user_id")
    username = data.get("username")
    print(f"{username} (ID: {user_id}) voted!")

    # 2. Reward the user in your bot
    # give_coins(user_id, 100)

    return jsonify({"ok": True}), 200

if __name__ == "__main__":
    app.run(port=3000)

Python (aiohttp) — Handle vote webhook (async)

from aiohttp import web

WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET"

async def vote_handler(request):
    if request.headers.get("Authorization") != WEBHOOK_SECRET:
        return web.json_response({"error": "Unauthorized"}, status=401)

    data = await request.json()
    user_id = data.get("user_id")
    username = data.get("username")
    print(f"{username} (ID: {user_id}) voted!")

    # await give_coins(user_id, 100)
    return web.json_response({"ok": True})

app = web.Application()
app.router.add_post("/webhook", vote_handler)
web.run_app(app, port=3000)

Code Examples

Node.js — Fetch a bot

const fetch = require("node-fetch");

const res = await fetch("https://api.dlist.space/api/bot/795845038922924113");
const data = await res.json();

console.log(data.data.name);          // "Accord"
console.log(data.data.stats.votes);   // 42

Python — Fetch a bot

import requests

r = requests.get("https://api.dlist.space/api/bot/795845038922924113")
data = r.json()

print(data["data"]["name"])          # Accord
print(data["data"]["stats"]["votes"])  # 42

Node.js — Post bot stats with token

const fetch = require("node-fetch");

await fetch("https://api.dlist.space/api/bot/YOUR_BOT_ID/stats", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_BOT_TOKEN"
  },
  body: JSON.stringify({
    server_count: 1500,
    user_count: 75000,
    shard_count: 4
  })
});

Python — Post bot stats with token

import requests

requests.post(
    "https://api.dlist.space/api/bot/YOUR_BOT_ID/stats",
    json={"server_count": 1500, "user_count": 75000, "shard_count": 4},
    headers={"Authorization": "Bearer YOUR_BOT_TOKEN"}
)