Look up servers and bots listed on DiscoListing, reward people who vote for you, and post your bot's server count so it shows on your page.
https://discolisting.com/api/v1Server and bot lookups need no key. They return public data for approved, non-NSFW listings, using a Discord ID, listing ID or slug.
Vote checks, vote history and bot stats updates require Authorization: Bearer <API_KEY>. Create a key in Dashboard → your listing → Integrations. It only works for that listing.
Public lookups: 60 requests/minute per IP, even if you send a key. Key-required endpoints: 120 requests/minute per key. Exceeding either limit returns 429 with a Retry-After header in seconds.
Send your key in the Authorization header on every request that needs one. Keys start with lst_; create and revoke them in your dashboard.
Authorization: Bearer lst_your_api_keyGET/api/v1/servers/{id}
id | URL · required · string | Discord ID, listing ID or slug |
curl "https://discolisting.com/api/v1/servers/123456789012345678"{
"id": "6650f1c2a4b5c6d7e8f90123",
"guildId": "123456789012345678",
"slug": "cozy-gamers",
"name": "Cozy Gamers",
"shortDescription": "A friendly community for cozy and indie games.",
"url": "https://discolisting.com/server/cozy-gamers",
"inviteUrl": "https://discord.gg/cozy",
"iconUrl": "https://cdn.discordapp.com/icons/123456789012345678/abc.webp",
"memberCount": 1240,
"onlineCount": 312,
"qualityScore": 72.4,
"votes30d": 87,
"tags": [
"minecraft"
],
"category": "gaming",
"languages": [
"english"
],
"nsfw": false
}id | string | Listing ID |
guildId | string | Discord server ID |
slug | string | Short name used in page URLs |
name | string | Display name |
shortDescription | string | One-line description |
url | URL | Page on this site |
inviteUrl | URL or null | Link to join the server or add the bot |
iconUrl | URL or null | Icon image |
memberCount | number | Members, from Discord |
onlineCount | number | Members online, from Discord |
qualityScore | number | Quality Score, 0–100 |
votes30d | number | Votes in the last 30 days |
tags | list of string | Tag slugs |
category | string | Category slug |
languages | list of string | Language slugs |
nsfw | boolean | Adult content: true for age-restricted listings |
404Nothing found with that ID or slug (unapproved, hidden and banned listings are not public).GET/api/v1/bots/{id}
id | URL · required · string | Discord ID, listing ID or slug |
curl "https://discolisting.com/api/v1/bots/123456789012345678"{
"id": "6650f1c2a4b5c6d7e8f90123",
"botId": "234567890123456789",
"slug": "cozy-gamers",
"name": "Cozy Gamers",
"shortDescription": "A friendly community for cozy and indie games.",
"url": "https://discolisting.com/server/cozy-gamers",
"inviteUrl": "https://discord.gg/cozy",
"iconUrl": "https://cdn.discordapp.com/icons/123456789012345678/abc.webp",
"serverCount": 5200,
"shardCount": 2,
"statsUpdatedAt": "2026-10-02T14:30:00.000Z",
"qualityScore": 72.4,
"votes30d": 87,
"tags": [
"minecraft"
],
"prefix": "!",
"nsfw": false
}id | string | Listing ID |
botId | string | Discord application (bot) ID |
slug | string | Short name used in page URLs |
name | string | Display name |
shortDescription | string | One-line description |
url | URL | Page on this site |
inviteUrl | URL | Link to join the server or add the bot |
iconUrl | URL or null | Icon image |
serverCount | number | Servers the bot is in, as reported by its developer |
shardCount | number | Number of shards |
statsUpdatedAt | date (ISO 8601) or null | When the developer last posted stats |
qualityScore | number | Quality Score, 0–100 |
votes30d | number | Votes in the last 30 days |
tags | list of string | Tag slugs |
prefix | string or null | Command prefix, if any |
nsfw | boolean | Adult content: true for age-restricted listings |
404Nothing found with that ID or slug (unapproved, hidden and banned listings are not public).GET/api/v1/votes/check
True when the Discord user voted for the listing that owns the API key within the current cooldown window.
userId | Query · required · string | Discord user ID |
curl "https://discolisting.com/api/v1/votes/check?userId=123456789012345678" \
-H "Authorization: Bearer lst_your_api_key"{
"voted": true,
"votedAt": "2026-10-02T14:30:00.000Z",
"nextVoteAt": "2026-10-02T14:30:00.000Z",
"cooldownHours": 24
}voted | boolean | True when the user voted within the cooldown |
votedAt | date (ISO 8601) or null | Time of their latest vote |
nextVoteAt | date (ISO 8601) or null | When they can vote again |
cooldownHours | number | Hours between votes: 24 for servers, 12 for bots |
401Missing, malformed or revoked API key.GET/api/v1/votes
Newest first. Paginate with `before` (the `votedAt` of the last item).
limit | Query · number | |
before | Query · date (ISO 8601) |
curl "https://discolisting.com/api/v1/votes" \
-H "Authorization: Bearer lst_your_api_key"{
"votes": [
{
"userId": "345678901234567890",
"votedAt": "2026-10-02T14:30:00.000Z"
}
]
}votes | list of object | Newest first |
401Missing, malformed or revoked API key.POST/api/v1/stats
Report your bot server count. Sharded bots can post per shard with `shardId` and `shardCount`; the total is the sum of shard reports from the last 24 hours. Post at most once a minute per shard.
serverCount | number | Servers the bot is in, as reported by its developer |
shardCount | number | Number of shards |
shardId | number | Shard sending this report (sharded bots only) |
curl -X POST "https://discolisting.com/api/v1/stats" \
-H "Authorization: Bearer lst_your_api_key" \
-H "Content-Type: application/json" \
-d '{"serverCount":5200,"shardCount":2,"shardId":0}'{
"serverCount": 5200,
"shardCount": 2
}serverCount | number | Servers the bot is in, as reported by its developer |
shardCount | number | Number of shards |
400The request is invalid; the message says which field.401Missing, malformed or revoked API key.429Too many requests. Wait the number of seconds in the Retry-After header.Instead of asking us, let us tell you: add a webhook in Integrations and we send a POST to your URL for every vote. Check the X-Listing-Signature header (t=<unix time>,v1=<signature>, an HMAC-SHA256 of t + "." + raw body with your signing secret) and ignore requests older than 5 minutes. Failed deliveries are retried for about 30 minutes.
{
"id": "6650f1c2a4b5c6d7e8f90456",
"event": "vote",
"test": false,
"data": {
"type": "vote",
"listingId": "6650f1c2a4b5c6d7e8f90123",
"userId": "345678901234567890",
"isWeekend": false,
"votedAt": "2026-10-02T14:30:00.000Z"
}
}Optional helper that wraps everything above, including webhook verification. No dependencies; works in Node, Bun, Deno and edge runtimes.
npm install discolistingimport { ListingClient, verifyWebhook } from 'discolisting'
const client = new ListingClient({
apiKey: process.env.LISTING_API_KEY,
})
// Post your server count every 30 minutes
client.autoPost(() => ({ serverCount: bot.guilds.cache.size }))
// Reward voters (24 h cooldown for servers, 12 h for bots)
const { voted, nextVoteAt } = await client.hasVoted(interaction.user.id)
// In your webhook route (use the raw request body)
const ok = await verifyWebhook(rawBody, req.headers['x-listing-signature'], process.env.WEBHOOK_SECRET)Also included: getServer, getBot, getVotes, parseWebhook and widgetUrl for the live embed widget. Errors throw ListingApiError with the status and, on rate limits, retryAfter.
Practical guides for finding your people and growing a welcoming server.
Build trust first
3 min read · Community guide
Set up Discord moderation with clear roles, tested permissions, AutoMod alerts and a reporting process. Includes checks for new members, bots and staff access.
A place worth staying
3 min read · Community guide
Write Discord server rules people can understand and moderators can apply fairly. Use practical examples for privacy, promotion, reporting and appeals.