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

npm Package

The official dlist.space npm package gives you a typed JavaScript/TypeScript client with automatic stats posting, rate-limit handling, and a built-in webhook listener — no raw fetch calls needed.

terminal
npm install dlist.space
Post stats automatically (Discord.js)
const { Client, GatewayIntentBits } = require("discord.js");
const DlistClient = require("dlist.space");

const bot  = new Client({ intents: [GatewayIntentBits.Guilds] });
const dlist = new DlistClient({
  botId : "YOUR_BOT_ID",
  token : "YOUR_DLIST_TOKEN",
});

bot.once("ready", () => {
  // Posts immediately, then every 30 min + on guild join/leave
  dlist.autopost(bot, {
    onPost : (res) => console.log("[dlist] Stats posted:", res.message),
    onError: (err) => console.error("[dlist] Error:", err.message),
  });
});

bot.login("YOUR_DISCORD_TOKEN");
Post stats manually
const DlistClient = require("dlist.space");

const dlist = new DlistClient({
  botId : "YOUR_BOT_ID",
  token : "YOUR_DLIST_TOKEN",
});

// Call whenever you want to update stats
const result = await dlist.postStats({
  server_count: bot.guilds.cache.size,
  user_count  : bot.users.cache.size,
  shard_count : bot.shard?.count,
});

if (result.rateLimited) {
  console.warn("Rate limited, retry in", result.retry_after, "seconds");
}
Check if a user voted
const { voted, timeLeft } = await dlist.hasVoted(userId);

if (voted) {
  const hours = (timeLeft / 3_600_000).toFixed(1);
  await interaction.reply(`✅ Thanks for voting! Next vote in ${hours}h.`);
} else {
  await interaction.reply("❌ You haven't voted yet — vote to earn rewards!");
}
Receive vote webhooks (standalone server)
const { WebhookListener } = require("dlist.space");

const listener = new WebhookListener({
  webhookKey: "YOUR_WEBHOOK_SECRET",
  port      : 3000,
  path      : "/dlist/webhook",
});

listener.on("vote", ({ user_id, username, weekend }) => {
  const coins = weekend ? 200 : 100;   // double rewards on weekends
  console.log(`${username} voted — awarding ${coins} coins`);
  // giveCoins(user_id, coins);
});

await listener.listen();
console.log("Listening for votes on port 3000");
Receive vote webhooks (Express middleware)
const express = require("express");
const { WebhookListener } = require("dlist.space");

const app      = express();
const listener = new WebhookListener({ webhookKey: "YOUR_WEBHOOK_SECRET" });

app.use(express.json());
app.post("/dlist/webhook", listener.middleware());

listener.on("vote", ({ user_id, username, weekend, test }) => {
  if (test) return console.log("[dlist] Test webhook received");
  const coins = weekend ? 200 : 100;
  console.log(`${username} voted — awarding ${coins} coins`);
});

app.listen(3000);

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

Stats Posting

1 post / 5 min

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/...",
  "weekend":  true
}

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

Weekend bonus — weekend is true when the vote is cast on Saturday or Sunday (UTC). Use this to reward voters with double coins, XP, or any other bonus.

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, weekend } = req.body;
  console.log(`${username} (ID: ${user_id}) voted! Weekend: ${weekend}`);

  // 2. Reward the user — double rewards on weekends
  const coins = weekend ? 200 : 100;
  // e.g. giveCoins(user_id, coins);

  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")
    weekend = data.get("weekend", False)
    print(f"{username} (ID: {user_id}) voted! Weekend: {weekend}")

    # 2. Reward the user — double rewards on weekends
    coins = 200 if weekend else 100
    # give_coins(user_id, coins)

    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")
    weekend = data.get("weekend", False)
    print(f"{username} (ID: {user_id}) voted! Weekend: {weekend}")

    # coins = 200 if weekend else 100
    # await give_coins(user_id, coins)
    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"}
)

Check Vote Examples

Use POST /api/bot/:id/checkvote to verify a user voted and reward them inside your bot.

Node.js (discord.js) — Check if a user voted
const axios = require("axios");

const BOT_ID    = "YOUR_BOT_ID";
const BOT_TOKEN = "YOUR_BOT_TOKEN";

async function hasVoted(userId) {
  const res = await axios.post(
    "https://api.dlist.space/api/bot/" + BOT_ID + "/checkvote",
    { user_id: userId },
    { headers: { Authorization: "Bearer " + BOT_TOKEN } }
  );
  return res.data;
  // { status: 200, voted: true, timeLeft: 39600000 }
}

// In your slash command handler:
client.on("interactionCreate", async (interaction) => {
  if (!interaction.isChatInputCommand()) return;

  if (interaction.commandName === "checkvote") {
    const { voted, timeLeft } = await hasVoted(interaction.user.id);
    if (voted) {
      const hours = (timeLeft / 3_600_000).toFixed(1);
      await interaction.reply(`✅ You voted! Next vote in ${hours}h.`);
    } else {
      await interaction.reply("❌ You haven't voted yet! Vote at https://api.dlist.space");
    }
  }
});
Python (discord.py) — Check if a user voted
import requests
import discord
from discord.ext import commands

BOT_ID    = "YOUR_BOT_ID"
BOT_TOKEN = "YOUR_BOT_TOKEN"
BASE_URL  = "https://api.dlist.space"

def has_voted(user_id: str) -> dict:
    """Returns {'status': 200, 'voted': bool, 'timeLeft': int}"""
    r = requests.post(
        f"{BASE_URL}/api/bot/{BOT_ID}/checkvote",
        json={"user_id": user_id},
        headers={"Authorization": f"Bearer {BOT_TOKEN}"},
    )
    return r.json()

bot = commands.Bot(command_prefix="!")

@bot.command()
async def checkvote(ctx):
    result = has_voted(str(ctx.author.id))
    if result["voted"]:
        hours = result["timeLeft"] / 3_600_000
        await ctx.send(f"✅ You voted! Next vote in {hours:.1f}h.")
    else:
        await ctx.send(f"❌ You haven't voted! Vote at {BASE_URL}")
Java (JDA) — Check if a user voted
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

public class VoteChecker {
    private static final String BASE_URL  = "https://api.dlist.space";
    private static final String BOT_ID    = "YOUR_BOT_ID";
    private static final String BOT_TOKEN = "YOUR_BOT_TOKEN";

    /**
     * Returns true if the user has an active vote (within 12-hour cooldown).
     */
    public static boolean hasVoted(String userId) throws Exception {
        HttpClient client = HttpClient.newHttpClient();

        String body = "{\"user_id\":\"" + userId + "\"}";

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/api/bot/" + BOT_ID + "/checkvote"))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer " + BOT_TOKEN)
            .POST(BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> resp = client.send(
            request, HttpResponse.BodyHandlers.ofString()
        );

        // Simple check without a JSON library:
        return resp.body().contains("\"voted\":true");
    }

    // In your JDA slash command listener:
    // boolean voted = VoteChecker.hasVoted(event.getUser().getId());
    // if (voted) event.reply("✅ You voted!").queue();
    // else       event.reply("❌ Vote at https://api.dlist.space").queue();
}