Bot Endpoints — FBL v1 API

The bot endpoints let you search the FBL bot directory, retrieve details for a specific bot, check vote history, post server count statistics, and read or upload the bot's commands. All bot endpoints are subject to a rate limit of 60 requests per minute.

The :id in every /bots/:id/... route accepts either the bot's Fluxer application/client id (recommended — the same snowflake your bot logs in with) or the FBL listing UUID. Use whichever is more convenient.

---

GET /bots

Searches the FBL bot directory with optional filtering, sorting, and pagination.

curl "https://fbl.gg/api/v1/bots?limit=10&sort=votes"

Query parameters

Response fields

---

GET /bots/:id

Returns a single Bot object by its FBL listing id. Returns 404 Not Found if no bot with that id is listed on FBL.

curl https://fbl.gg/api/v1/bots/88888888-8888-8888-8888-888888888888 \
  -H "Authorization: your-fbl-token-here"

See the Bot structure section below for the full list of fields. Owner-only fields (webhook URL, webhook secret, API token hash) are stripped from the public response.

---

GET /bots/:id/votes

Returns the last 1,000 unique voters for the specified bot, most-recent first. Each entry includes the voter's username, Fluxer user id, and avatar URL.

curl https://fbl.gg/api/v1/bots/88888888-8888-8888-8888-888888888888/votes \
  -H "Authorization: your-fbl-token-here"

Auth: required. Token must belong to the bot in the path.

Response

Returns an array of voter objects:

Duplicates are removed — a user who has voted multiple times appears once, at their most recent timestamp. For higher-throughput consumers, use the vote webhook instead.

---

GET /bots/:id/stats

Returns the current server count for a bot.

curl https://fbl.gg/api/v1/bots/88888888-8888-8888-8888-888888888888/stats

Auth: public.

Response fields

---

GET /bots/:id/check

Checks whether a specific user has an active vote for the bot. Safe to call even if your bot has more than 1,000 monthly votes.

curl "https://fbl.gg/api/v1/bots/88888888-8888-8888-8888-888888888888/check?userId=1493230087487714059" \
  -H "Authorization: your-fbl-token-here"

Auth: required.

Query parameters

Response

{ "voted": 1 }

A voted value of 1 means the user has voted in the past 12 hours. A value of 0 means they have not.

---

POST /bots/:id/stats

Posts updated server count statistics for the specified bot. Call this endpoint whenever your bot's server count changes, for example when it joins or leaves a guild.

curl -X POST https://fbl.gg/api/v1/bots/88888888-8888-8888-8888-888888888888/stats \
  -H "Authorization: your-fbl-token-here" \
  -H "Content-Type: application/json" \
  -d '{ "server_count": 1234 }'

Auth: required. Token must belong to the bot in the path.

Request body

Response

Returns 200 { "ok": true } on success.

---

GET /bots/:id/commands

Returns the bot's command list, in the order the owner set. The same list shows in the bot's Commands tab and in FBL's command search.

curl https://fbl.gg/api/v1/bots/88888888-8888-8888-8888-888888888888/commands

Auth: public.

Response

{
  "prefix": "!",
  "updated_at": "2026-10-17T09:12:00.000Z",
  "commands": [
    { "name": "remind", "description": "Set a reminder", "usage": "remind <time> <message>", "category": "Utility", "kind": "prefix" },
    { "name": "play", "description": "Play a song", "usage": null, "category": "Music", "kind": "slash" }
  ]
}

---

PUT /bots/:id/commands

Uploads the bot's full command list, replacing the old one. Call it when your bot starts so FBL always shows your current commands.

curl -X PUT https://fbl.gg/api/v1/bots/88888888-8888-8888-8888-888888888888/commands \
  -H "Authorization: your-fbl-token-here" \
  -H "Content-Type: application/json" \
  -d '{ "commands": [{ "name": "remind", "description": "Set a reminder", "usage": "remind <time> <message>", "category": "Utility" }] }'

Auth: required. Token must belong to the bot in the path.

Request body

Each command:

Response

Returns 200 { "ok": true, "count": 2 } on success, or 400 with the first problem, e.g. commands[3].name: "help" is listed twice.

---

Bot structure

Every bot endpoint that returns a Bot object uses the following structure:

Field	Type	Description
id	string	FBL listing UUID
name	string	Bot display name
username	string	Fluxer username
avatar	string?	Full CDN URL of the bot's avatar
short_description	string	Short description shown on listings
long_description	string?	Full description (may contain Markdown)
tags	string[]	List of category tag slugs
language_code	string?	Primary ISO 639-1 language code
prefix	string?	Bot command prefix
invite_url	string?	Custom invite URL
website_url	string?	Bot's website URL
support_server_url	string?	Support server invite URL
github_url	string?	GitHub repository URL
owner_ids	string[]	FBL profile ids of the bot's owners
vote_count	number	All-time vote count
monthly_vote_count	number	Vote count for the current month
server_count	number?	Current server count (if posted)
certified	boolean	Whether the bot is FBL certified
featured	boolean	Whether the bot is currently featured
created_at	string	ISO 8601 date the bot was added to FBL

Example bot object

{
  "id": "88888888-8888-8888-8888-888888888888",
  "name": "Nimbus",
  "username": "nimbus",
  "avatar": "https://fluxerusercontent.com/avatars/.../a.png",
  "short_description": "A modern moderation and utility bot.",
  "long_description": "Nimbus helps you run your Fluxer server…",
  "tags": ["moderation", "utility", "logging"],
  "language_code": "en",
  "prefix": "n!",
  "invite_url": "https://fluxer.gg/oauth2/authorize?...",
  "website_url": "https://nimbus.gg",
  "support_server_url": "https://fluxer.gg/ALjYue2O",
  "github_url": null,
  "owner_ids": ["88888888-aaaa-bbbb-cccc-000000000001"],
  "vote_count": 23894,
  "monthly_vote_count": 412,
  "server_count": 120540,
  "certified": false,
  "featured": true,
  "created_at": "2025-09-02T14:03:22.000Z"
}