> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fluxerlist.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fluxerlist.com/_mcp/server.

# API overview

The FluxerList API gives server and bot owners programmatic access to their own listings. All endpoints return JSON.

```text
https://fluxerlist.com/api/v1
```

#### [Update bot stats](/api/endpoints/bots/update-bot-stats)

Set the server count shown on a bot listing.

#### [Get a bot or server](/api/endpoints/bots/get-bot)

Look up the public listing fields for any bot or server.

#### [Check a vote](/api/endpoints/voters/check-bot-vote)

See if a specific user currently has an active vote.

#### [Server voters](/api/endpoints/voters/list-server-voters)

List who voted for your server.

#### [Bot voters](/api/endpoints/voters/list-bot-voters)

List who voted for your bot.

#### [Bump status](/api/endpoints/bumps/get-server-bumps)

See when your server can next bump, its streak, and its bump history.

#### [Stat badges](/api/endpoints/widgets/get-bot-widget)

Embeddable SVG badges - no key required.

#### [Current user](/api/endpoints/users/get-me)

Look up the account a key belongs to, and its listings.

## Authentication

Every request needs an API key, sent as a bearer token. Keys start with `fl_`.

```text
Authorization: Bearer fl_your_api_key_here
```

A key belongs to one account. Lookup endpoints (getting a bot, a server, or `/users/@me`) work for any valid key. Everything else only works on listings that account owns - or, for bot stats and vote checks, on bots where it's a listed developer. Widget badges don't need a key at all.

Any FluxerList account can generate its own key from the Dashboard's Developer tab - no request or approval needed. See [API quickstart](/api-quickstart#get-a-key).

## Pagination

List endpoints use `page` and `limit` query parameters, and return `total`, `page`, and `limit` alongside the results.

| Parameter | Default | Maximum |
| --------- | ------- | ------- |
| `page`    | 1       | none    |
| `limit`   | 50      | 100     |

## Errors

Errors return an appropriate HTTP status and a JSON body with an `error` message.

```json
{ "error": "Forbidden" }
```

| Status | Meaning                                                                                                                                            |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | The request body was invalid.                                                                                                                      |
| `401`  | The key is missing or invalid.                                                                                                                     |
| `403`  | The key doesn't belong to the listing's owner.                                                                                                     |
| `404`  | The listing wasn't found.                                                                                                                          |
| `429`  | The key is rate limited.                                                                                                                           |
| `5xx`  | Something went wrong on FluxerList's side. Retry after a moment, and check the [status page](https://status.fluxerlist.com) if it keeps happening. |

## Rate limits

Keys can be rate limited. When one is, the response is `429` with a `Retry-After` header in seconds, and a body that includes `remaining` and `reset`, the time until the limit resets in milliseconds. Wait for `Retry-After` before retrying, and cache responses where you can.

## Guides

#### [API quickstart](/api-quickstart)

Get a key and make your first request.

#### [Find your listings](/find-your-listings)

Look up your account and the IDs of what you own.

#### [Sync your server count](/sync-server-count)

Post your bot's guild count on a schedule.

#### [Check a vote](/check-a-vote)

Look up one user's vote status instantly.

#### [Reward your voters](/reward-voters)

Fetch every voter and thank them.

#### [Embed a stat badge](/stat-badges)

Add a live badge to your README, no key needed.