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.spacenpm 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.
npm install dlist.space
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");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");
}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!");
}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");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.
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
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);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)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
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); // 42import requests
r = requests.get("https://api.dlist.space/api/bot/795845038922924113")
data = r.json()
print(data["data"]["name"]) # Accord
print(data["data"]["stats"]["votes"]) # 42const 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
})
});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.
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");
}
}
});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}")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();
}