Bot Endpoints — FBL v1 API

Search bots, fetch individual bot details, retrieve voter lists, check vote status, read stats, and post server counts using the FBL v1 bot endpoints.

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

Bot endpoints have stricter rate limits than other v1 endpoints. Stay within 60 requests per minute to avoid 429 Too Many Requests errors.

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

q string

Substring match against name + short description. Alias: query.

category string

Comma-separated list of tag slugs. Overlap match against the bot's tag list. Alias: tags.

language string

Comma-separated ISO 639-1 codes. Filters by the bot's primary language_code. Alias: langs.

invites string

Server-count bucket. One of lt100, 100-1000, 1000-10000, gt10000.

votes number

Minimum vote_count.

sort string default:"votes"

One of votes, newest, monthly_votes, recently_updated, invites. Descending on the sort column; featured bots always float first.

limit number default:"24"

Number of bots to return. Clamped to 100.

offset number default:"0"

Number of bots to skip before returning results. Use with limit for pagination.

page number default:"1"

Alternative to offset. Computed as offset = (page - 1) * limit.

Response fields

results object[] required

Array of Bot objects matching the query. See Bot structure below.

limit number required

The limit value used for this request.

offset number required

The offset value used for this request.

count number required

Number of results returned in this response.

total number required

Total number of bots matching the search query across all pages.

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:

username string required

The voter's Fluxer username.

id string required

The voter's Fluxer snowflake id.

avatar string?

Full CDN URL of the voter's avatar. null if the user has no custom avatar.

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

server_count number

Current server count. 0 if the bot has never posted stats.

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

userId string required

The Fluxer snowflake id of the user to check.

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

server_count number required

The number of servers your bot is in.

Response

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

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"
}

Introduction

Users