BotsList.net

1.0.0OAS 1.0

Use the BotsList API to check votes, retrieve bot info, post stats, and receive real-time vote webhooks in your Discord bot.

Base URLhttps://botslist.net/api/v1

🔓 Authorize⚡ 1,000 req / hr📄 JSON responses

🔒

Authentication Required

All endpoints (except the widget badge) require Authorization: Bearer bl_your_key. Generate a key from your Dashboard. Keys can be revoked at any time. Maximum 5 keys per account.

Parameters

NameInTypeRequiredDescription

idpathintegertrueBotsList numeric bot ID

Responses

idintegerBotsList internal ID

discordIdstringDiscord application snowflake ID

namestringBot display name

shortDescriptionstringOne-line description

tagsstring[]Category tags

votesintegerAll-time vote count

monthlyVotesintegerVotes this month (resets 1st)

certifiedbooleanBotsList certified status

premiumbooleanPremium status

Example Value

{
  "id": 42,
  "discordId": "1234567890",
  "name": "My Awesome Bot",
  "shortDescription": "The best bot ever made",
  "tags": ["music", "fun"],
  "votes": 1337,
  "monthlyVotes": 42,
  "certified": false,
  "premium": false
}

401Unauthorized — missing or invalid API key

404Bot not found or not approved

💡 Votes last 12 hours. On Sat & Sun votes count 2× automatically.

Parameters

NameInTypeRequiredDescription

idpathintegertrueBotsList numeric bot ID

userIdquerystringtrueDiscord user snowflake ID to check

Responses

votedbooleantrue if voted in the last 12 hours

votedAtstring | nullISO 8601 timestamp of last vote, or null

Example Value

{
  "voted": true,
  "votedAt": "2026-03-06T14:22:00.000Z"
}

401Unauthorized

404Bot not found

Parameters

NameInTypeRequiredDescription

idpathintegertrueBotsList numeric bot ID

Request Body · application/json

FieldInTypeRequiredDescription

guildCountbodyintegertrueTotal guild (server) count

shardCountbodyintegerfalseShard count (optional)

POST /api/v1/bots/42/stats
Authorization: Bearer bl_your_api_key_here
Content-Type: application/json

{
  "guildCount": 15000,
  "shardCount": 4
}

Responses

{ "ok": true }

401Unauthorized

403Forbidden — you do not own this bot

🕐 Badges are cached for 5 minutes. No API key required.

Parameters

NameInTypeRequiredDescription

idpathintegertrueBotsList numeric bot ID

stylequerystringfalsecompact for flat single-line badge; omit for card

Responses

<!-- Compact flat badge -->
<img src="https://botslist.net/api/bots/42/widget.svg?style=compact" alt="My Bot" />

<!-- Full card (default) -->
<img src="https://botslist.net/api/bots/42/widget.svg" alt="My Bot" />

Configure your URL in Dashboard → Settings → Webhook. BotsList POSTs on every vote. Respond 2xx within 5 seconds.

Payload Fields

FieldInTypeRequiredDescription

botIdbodystringtrueDiscord bot snowflake ID

userIdbodystringtrueDiscord user snowflake ID

typebody"upvote"trueEvent type

isWeekendbodybooleantruetrue on Sat/Sun — votes count 2x

votedAtbodystringtrueISO 8601 vote timestamp

Example Payload

{
  "botId": "1234567890",
  "userId": "9876543210",
  "type": "upvote",
  "isWeekend": false,
  "votedAt": "2026-03-06T14:22:00.000Z"
}

Signature Verification (Node.js / TS)

Every delivery includes X-BotList-Signature — HMAC-SHA256 of the raw body. Always verify before processing.

import { createHmac, timingSafeEqual } from 'crypto'

function verify(rawBody: string, sig: string, secret: string) {
  const expected = createHmac('sha256', secret)
    .update(rawBody).digest('hex')
  const a = Buffer.from(sig)
  const b = Buffer.from(expected)
  return a.length === b.length && timingSafeEqual(a, b)
}

Returns all keys for your account. The raw key value is never returned after initial creation.

Responses

200Array of API key objects

401Not authenticated

The plain-text key is returned once only — store it immediately. Maximum 5 keys per account.

Responses

201Key created — contains the one-time plaintext value

403Key limit reached (max 5)

Parameters

NameInTypeRequiredDescription

keyIdpathstringtrueID of the key to revoke

Responses

200Key revoked successfully

404Key not found

Authenticate with your bot's Bridge key: Authorization: Bridge blst_bridge_<key>. Bridge keys are per-bot and are created from your bot's dashboard. This is separate from your personal API key.

Request Body

NameInTypeRequiredDescription

onlinebodybooleantrueWhether the bot process is currently online

pingMsbodyintegerfalseWebSocket ping latency in milliseconds

guildCountbodyintegerfalseNumber of guilds the bot is in — also synced to bot profile

shardCountbodyintegerfalseNumber of active shards — also synced to bot profile

memoryMbbodyintegerfalseCurrent RSS memory usage in megabytes

cpuPercentbodyintegerfalseCPU utilisation percentage (0–100)

uptimeSecondsbodyintegerfalseSeconds since the bot process last started

errorsLastHourbodyintegerfalseUnhandled error count in the rolling last 60 minutes

lastCrashAtbodystringfalseISO 8601 timestamp of last crash, or null

Example Request

POST /api/bridge/heartbeat
Authorization: Bridge blst_bridge_your_key_here
Content-Type: application/json

{
  "online": true,
  "pingMs": 42,
  "guildCount": 15000,
  "shardCount": 4,
  "memoryMb": 312,
  "cpuPercent": 18,
  "uptimeSeconds": 86400,
  "errorsLastHour": 0
}

Responses

200{ "ok": true }

401Missing or invalid Bridge key

Errors are stored and surfaced in your bot's dashboard. Uses the same Bridge key auth as the heartbeat endpoint.

Request Body

NameInTypeRequiredDescription

messagebodystringtrueError message — max 2,000 characters

stackbodystringfalseFull stack trace — max 10,000 characters

Example Request

POST /api/bridge/error
Authorization: Bridge blst_bridge_your_key_here
Content-Type: application/json

{
  "message": "UnhandledPromiseRejection: TypeError: Cannot read properties of undefined",
  "stack": "TypeError: Cannot read properties of undefined\n    at Client.<anonymous> (src/events/messageCreate.js:14:22)"
}

Responses

200{ "ok": true }

401Missing or invalid Bridge key

Requires an active user session (cookie auth). Returns only tickets belonging to the authenticated user.

Response Fields

NameInTypeRequiredDescription

idbodyinteger—Ticket ID

subjectbodystring—Ticket subject line

categorybodystring—Auto-routed category (e.g. "bot-issue", "billing", "general")

prioritybodystring—Auto-assigned priority: low | normal | high | urgent

statusbodystring—open | in_progress | resolved | closed

updatedAtbodystring—ISO 8601 timestamp of last activity

Responses

200Array of ticket objects

401Not authenticated

Tickets are automatically categorised and prioritised based on your subject and body text. If you supply a botId, live diagnostics are run on that bot and attached to the ticket for staff context.

Request Body

NameInTypeRequiredDescription

subjectbodystringtrueTicket subject — 5 to 200 characters

bodybodystringtrueDetailed description — 10 to 4000 characters

botIdbodyintegerfalseBotsList bot ID — triggers automatic bot diagnostics on creation

Example Request

POST /api/support/tickets
Content-Type: application/json

{
  "subject": "Bot votes not counted after voting",
  "body": "Since yesterday votes go through on the site but the count on my bot profile isn't updating. Bot ID is 42.",
  "botId": 42
}

Example Response

{
  "id": 17,
  "category": "bot-issue",
  "priority": "high",
  "routing": {
    "team": "bot-support",
    "confidence": 0.91,
    "keywords": ["votes", "not updating"]
  }
}

Responses

201Ticket created — returns id, category, priority, and routing info

400Validation error — subject or body out of length bounds

401Not authenticated

Parameters

NameInTypeRequiredDescription

idpathintegertrueTicket ID

Responses

200{ ticket, messages: [{ id, content, isStaff, isSystem, createdAt, sender? }] }

403Ticket belongs to another user

404Ticket not found

If the ticket status is resolved, sending a reply will automatically reopen it.

Parameters

NameInTypeRequiredDescription

idpathintegertrueTicket ID

Request Body

NameInTypeRequiredDescription

contentbodystringtrueMessage content — 1 to 4000 characters

Responses

201Message created — returns the new message object

400Content too short or too long

403Ticket belongs to another user or is closed

400Bad RequestMissing or invalid parameters

401UnauthorizedMissing, invalid, or revoked API key

403ForbiddenYou do not own the requested resource

404Not FoundResource does not exist or is not approved

429Too Many RequestsRate limit exceeded — 1,000 req/hr

500Server ErrorUnexpected internal error

Error Shape

{
  "statusCode": 401,
  "message": "Missing API key"
}