---
title: "Bots and Categories"
description: "Create bots, organize categories, and read flags."
canonical: "https://developers.fnlb.net/docs/bots-and-categories"
markdown: "/docs/bots-and-categories.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.

# Bots and Categories

Bots live in **categories**. The API lists both, creates and updates them, and returns ids you reuse on the gateway, in the SDK, and in bulk import.

## List bots

[GET /bots](/api?method=GET&path=/bots) needs `bots.read` on an OAuth2 token, or an API token / session.

Each bot includes:

| Field | Meaning |
| :--- | :--- |
| `id` | Use as `{botId}` on every bot route. |
| `nickname` | Display name in FNLB. |
| `email` | Stored Epic email, when present. |
| `parent` | Category id, or omitted when uncategorized. |
| `flags` | `1` disabled, `2` public, `4` invalid auth. Combine with bitwise OR. |

[GET /bots/{botId}](/api?method=GET&path=/bots/{botId}) returns one bot with the same fields.

## Create and update

[POST /bots](/api?method=POST&path=/bots) creates a bot. It needs `bots.write`. The body includes Epic **device auth** (`email`, `nickname`, `deviceAuth` with `accountId`, `deviceId`, `secret`) and optional `parent` category id.

[PATCH /bots/{botId}](/api?method=PATCH&path=/bots/{botId}) updates nickname, parent, flags, or device auth. [DELETE /bots/{botId}](/api?method=DELETE&path=/bots/{botId}) removes the bot.

Account limits apply: unverified accounts allow fewer bots than verified ones. A `403` or `net.fnlb.errors.common.limit_exceeded` means you hit that cap.

## Categories

[GET /categories](/api?method=GET&path=/categories) lists categories with `id`, `name`, `flags`, and `config`. Needs `categories.read`.

[POST /categories](/api?method=POST&path=/categories) and [PATCH /categories/{categoryId}](/api?method=PATCH&path=/categories/{categoryId}) need `categories.write`.

The category `id` is what you pass as:

- `parent` when creating or moving a bot
- `categories` in the [Node.js SDK](/docs/sdk-node.md)
- `CATEGORIES` in [self-hosting](/self-hosting-guide)

## Managed categories

[GET /categories/managed](/api?method=GET&path=/categories/managed) and related routes serve FNLB-managed category assignment for clusters. Self-hosted and SDK users normally only need the ids from [GET /categories](/api?method=GET&path=/categories).

## Gateway vs API

[GET /bots on the API](/api?method=GET&path=/bots) is your catalog, including offline bots. [GET /bots on the gateway](/gateway?method=GET&path=/bots) is only bots with a live connection. Same `id`, different meaning.

<CardGroup cols={2}>
  <Card icon="code" href="/bot-commands" title="Bot commands">
    Run outfit, emote, and other commands on a bot id.
  </Card>
  <Card icon="speed" href="/bulk-operations" title="Bulk import and export">
    Move up to 100 bots in one import call.
  </Card>
</CardGroup>