---
title: "API Reference"
description: "How the API fits together, and where each area lives in the reference."
canonical: "https://developers.fnlb.net/docs/api-reference"
markdown: "/docs/api-reference.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.

# API Reference

The API reference next to these guides is the complete list of routes. This page is the map. Schemas, examples, and the try client live on each route, so they stay in one place.

Base URL:

```
https://api.fnlb.net/v1
```

Paths in the reference are relative to that URL. Authenticated calls use the header from [Authenticating](/docs/authenticating.md#header). OAuth2 tokens also need the scope named on the route. Limits are per route, not global. See [Rate limits](/docs/rate-limits.md#api).

## Areas

<CardGroup cols={2}>
  <Card icon="key" href="/api?method=POST&path=/oauth2/token" title="OAuth2">
    Exchange an authorization code for an access token.
  </Card>
  <Card icon="book" href="/api?method=GET&path=/user" title="User">
    Read the account that owns the token.
  </Card>
  <Card icon="api" href="/api?method=GET&path=/bots" title="Bots">
    List, create, update, import, and export bots.
  </Card>
  <Card icon="code" href="/api?method=GET&path=/categories" title="Categories">
    Group bots and read the ids a self-hosted cluster needs.
  </Card>
  <Card icon="code" href="/api?method=GET&path=/presets" title="Presets">
    Store reusable cosmetic setups.
  </Card>
  <Card icon="code" href="/api?method=POST&path=/bots/{botId}/commands/run" title="Commands">
    Run a command on one bot, such as changing an outfit.
  </Card>
  <Card icon="http" href="/api?method=GET&path=/bots/{botId}/friends" title="Social">
    Read friends, pending requests, and blocked users for a bot.
  </Card>
  <Card icon="gateway" href="/gateway" title="Gateway">
    Leave this API when you need live party and shard state.
  </Card>
</CardGroup>

## A first call

[GET /bots](/api?method=GET&path=/bots) returns the bots on the token's account. From a server:

```javascript
const response = await fetch('https://api.fnlb.net/v1/bots', {
  headers: { Authorization: 'Bearer FNLB_YOUR_API_TOKEN' }
});
if (!response.ok) throw new Error(await response.text());
const bots = await response.json();
```

While you are signed in to this portal, open that route and use **Try request**. The session token is sent for you and is not shown in the client.

Public routes, such as [GET /bots/public](/api?method=GET&path=/bots/public), do not take a token and are not rate limited.

## Commands

Cosmetic changes and other bot actions go through one route, [POST /bots/{botId}/commands/run](/api?method=POST&path=/bots/{botId}/commands/run). It needs the `commands.run` scope when you use an OAuth2 token.

```json
{
  "command": "outfit",
  "args": "Renegade Raider",
  "locale": "en"
}
```

The route page lists the fields and the errors. Do not cache a private copy of that schema. The reference is updated with the API.

`command` is the name only, with no category prefix. `args` is either one string or a list of up to 25 strings. `locale` is optional and picks the language of the reply.

```json
{
  "nonce": "…",
  "botName": "Alpha",
  "content": "Set outfit to Renegade Raider.",
  "format": 1
}
```

`format` is how to present `content`: `0` neutral, `1` success, `2` info, `3` warn, `4` error. The HTTP status is still `200` when the bot answered. A `4xx` means the API rejected the call before the bot ran it.

The reply does not include the party. Read that from the [gateway](/gateway.md) with the same bot id.

## What a bot object contains

[GET /bots](/api?method=GET&path=/bots) returns the bots owned by the token. Each object has:

| Field | Meaning |
| :--- | :--- |
| `id` | Bot id. This is `{botId}` on every other bot route, including the gateway. |
| `nickname` | Name shown in FNLB. |
| `email` | Epic account email stored with the bot, when one is set. |
| `parent` | Category id. The same value as `id` from [GET /categories](/api?method=GET&path=/categories). |
| `flags` | Bitfield. `1` disabled, `2` public, `4` invalid auth. Combine them. `6` is public and invalid auth. |

Creating a bot is [POST /bots](/api?method=POST&path=/bots) and needs `bots.write` on an OAuth2 token. Updating and deleting are [PATCH /bots/{botId}](/api?method=PATCH&path=/bots/{botId}) and [DELETE /bots/{botId}](/api?method=DELETE&path=/bots/{botId}).

## Friends, categories, presets

- [GET /bots/{botId}/friends](/api?method=GET&path=/bots/{botId}/friends), [pending](/api?method=GET&path=/bots/{botId}/friends/pending), and [blocked](/api?method=GET&path=/bots/{botId}/users/blocked) are the social lists for one bot.
- [GET /bots/{botId}/party/members/{memberId}](/api?method=GET&path=/bots/{botId}/party/members/{memberId}) reads one party member through the API. The full live party is on the gateway.
- [GET /categories](/api?method=GET&path=/categories) returns `id`, `name`, `flags`, and `config`. That `id` is what a self-hosted cluster and the SDK call a category.
- [GET /presets](/api?method=GET&path=/presets) stores reusable cosmetic setups. Apply one by running the matching command, not by a separate gateway call.

[GET /user](/api?method=GET&path=/user) is the account behind the token: `id`, `username`, and, when the token may see them, `email` and `connections`. That `id` is the gateway bucket.

## Deeper guides

<CardGroup cols={2}>
  <Card icon="api" href="/bots-and-categories" title="Bots and categories">
    Create bots, flags, and category ids.
  </Card>
  <Card icon="code" href="/bot-commands" title="Bot commands">
    Command run, chat messages, and reply format.
  </Card>
  <Card icon="speed" href="/bulk-operations" title="Bulk import and export">
    Import up to 100 bots or export device auth.
  </Card>
  <Card icon="book" href="/presets" title="Presets">
    Store cosmetic configs on your account.
  </Card>
  <Card icon="gateway" href="/public-bots" title="Public bots">
    Unauthenticated public bot listings.
  </Card>
</CardGroup>