> 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 quickstart

The FluxerList API lets server and bot owners read their voter data and keep a bot's listing accurate. It's small on purpose, and every endpoint is documented in the [API reference](/overview).

## Get a key

Every FluxerList account can generate its own key - no request, no ticket, no approval needed.

#### Open the Developer tab

Go to your dashboard and open **Developer**.

#### Generate a key

Generate a key and copy it straight away.

> **Warning**
>
> The key is shown **once**. If you lose it, revoke it from the same page and generate a new one.

Keys start with `fl_` and belong to your account, which is how the API knows which listings you own.

## Make your first request

Send the key as a bearer token. This call lists the people who voted for your bot.

**`curl`**

```bash title="curl"
curl "https://fluxerlist.com/api/v1/bots/YOUR_BOT_ID/voters?limit=10" \
  -H "Authorization: Bearer fl_your_api_key_here"
```

**`JavaScript`**

```javascript title="JavaScript"
const res = await fetch(
  "https://fluxerlist.com/api/v1/bots/YOUR_BOT_ID/voters?limit=10",
  { headers: { Authorization: `Bearer ${process.env.FLUXERLIST_KEY}` } },
);
const { total, voters } = await res.json();
console.log(`${total} votes`, voters);
```

**`Python`**

```python title="Python"
import os, requests

res = requests.get(
    "https://fluxerlist.com/api/v1/bots/YOUR_BOT_ID/voters",
    params={"limit": 10},
    headers={"Authorization": f"Bearer {os.environ['FLUXERLIST_KEY']}"},
)
data = res.json()
print(data["total"], "votes")
```

A successful response looks like this.

```json
{
  "total": 17,
  "page": 1,
  "limit": 10,
  "voters": [
    {
      "username": "jack",
      "fluxerId": "123456789",
      "votedAt": "2026-09-18T12:00:00.000Z"
    }
  ]
}
```

> **Warning**
>
> Keep your key out of your bot's public source and out of client-side code. Load it from an environment variable.

## Handle errors

| Status | Meaning                                        | What to do                                                      |
| ------ | ---------------------------------------------- | --------------------------------------------------------------- |
| `400`  | The request body was invalid.                  | Check the field types.                                          |
| `401`  | The key is missing or invalid.                 | Check the `Authorization` header.                               |
| `403`  | The key doesn't belong to the listing's owner. | Use the key from the account that owns the listing.             |
| `404`  | No listing matches the ID.                     | Check the ID. Servers use the guild ID, bots the Fluxer bot ID. |
| `429`  | The key is rate limited.                       | Wait for the `Retry-After` header, in seconds.                  |

Errors return JSON with an `error` message. A `429` also includes `remaining` (always `0`) and `reset`, a Unix timestamp in milliseconds for when that limit resets.

> **Tip**
>
> Cache what you fetch. Voter lists don't change second to second, so polling every few minutes is plenty.

## Rate limits

Each endpoint has its own limit, and every request also counts against a shared monthly cap per key across all endpoints combined. Exceeding either returns a `429`.

| Bucket                  | Limit       | Notes                                               |
| ----------------------- | ----------- | --------------------------------------------------- |
| Bot stats update        | 12/hour     | Post on startup, then roughly every 30 minutes.     |
| Vote check              | 60/min      | Cache the result on your end.                       |
| Voter lists             | 10/min      | Cache server-side for about a minute.               |
| Bump status and history | 10/min      | Cache server-side for about a minute.               |
| Everything else         | 20/min      | The default for any endpoint without its own limit. |
| All endpoints combined  | 3,000/month | Shared across every endpoint for a key.             |

## Next steps

#### [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)

Page through voters and thank them.

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

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