---
title: "FNLB Developer Documentation"
description: "What lives in this portal, and where to go next."
canonical: "https://developers.fnlb.net/docs"
markdown: "/docs.md"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fnlb.net/llms.txt
> Use this file to discover all available pages before exploring further.

# FNLB Developer Documentation

Guides, the API reference, the gateway reference, and your applications all live in this portal. Use a guide when you need to know how something works. Open the reference when you need the exact request.

## In this portal

- **Applications** hold the OAuth2 client id, client secret, redirect URIs, and scopes for an app that acts on someone else's account. Open them from the sidebar.
- **Guides** are these pages: authentication, OAuth2, rate limits, the gateway, and self-hosting.
- **API reference** is the interactive catalog for `https://api.fnlb.net/v1`. Each page shows the method, path, body, and responses, and you can try a request while you are signed in.
- **Gateway reference** is the same kind of catalog for `https://gateway.fnlb.net/v1`. It shows bots that are connected right now, their parties, and the shards serving them.

The API is where a bot is created, configured, and told to run a command. The gateway is where you read what that bot is doing after it is online.

## The same ids

These values show up in more than one place. Use the id from the first call as the path or query value on the next one.

| Value | Where you read it | Where you send it |
| :--- | :--- | :--- |
| Account id | [GET /user](/api?method=GET&path=/user) `id` | Gateway query `FNLB_BUCKET_ID` |
| Bot id | [GET /bots](/api?method=GET&path=/bots) `id` | Command, friends, and [GET /bots/{botId}](/gateway?method=GET&path=/bots/{botId}) |
| Category id | [GET /categories](/api?method=GET&path=/categories) `id` | Bot `parent`, SDK `categories`, self-host `CATEGORIES` |

A bot that is offline is still in the API list. It is missing from the gateway list until that process connects.

## A call, then the live state

1. Create an [API token](/docs/authenticating.md#header) for your own account, or an [OAuth2 access token](/docs/oauth2.md#authorize-url) after a user approves your [application](/).
2. [GET /bots](/api?method=GET&path=/bots) returns `id` and `parent` for each bot. `parent` is the category id.
3. [POST /bots/{botId}/commands/run](/api?method=POST&path=/bots/{botId}/commands/run) runs a command on that id. The reply is text plus a format code, not the new party state.
4. [GET /bots/{botId}](/gateway?method=GET&path=/bots/{botId}) on the gateway, with your account id as `FNLB_BUCKET_ID`, returns the party and presence after the bot is connected.
5. To run the process yourself, pass the category id to the [Node.js SDK](/docs/sdk-node.md) or to `CATEGORIES` in [self-hosting](/self-hosting-guide). [GET /shards](/gateway?method=GET&path=/shards) then shows that cluster.

## What you can build

- Change cosmetics and run other bot commands through [POST /bots/{botId}/commands/run](/api?method=POST&path=/bots/{botId}/commands/run).
- List and edit bots, categories, and presets from the [API reference](/api.md).
- Read live party and presence state from the [gateway](/gateway.md).
- Run the bots yourself with the [Node.js SDK](/docs/sdk-node.md) or the [self-hosting](/self-hosting-guide) cluster.

## Start here

<CardGroup cols={2}>
  <Card icon="code" href="/" title="Applications">
    Create an OAuth2 client and copy its id and secret.
  </Card>
  <Card icon="lock" href="/authenticating#header" title="Authenticating">
    Send an API token or an access token on each request.
  </Card>
  <Card icon="key" href="/oauth2#authorize-url" title="OAuth2">
    Ask a user to approve your app, then exchange the code.
  </Card>
  <Card icon="api" href="/api" title="API reference">
    Browse every API route and try one with your account.
  </Card>
  <Card icon="gateway" href="/gateway" title="Gateway reference">
    Read connected bots, parties, and shards.
  </Card>
  <Card icon="server" href="/self-hosting-guide" title="Self-hosting">
    Run your own cluster against the same API.
  </Card>
</CardGroup>