---
title: "Gateway Guide"
description: "Real-time events from running bots."
canonical: "https://developers.fnlb.net/docs/gateway"
markdown: "/docs/gateway.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.

# Gateway Guide

The gateway reports what your bots are doing right now: who is connected, who is in the party, and which shard is serving them. Creating a bot, editing it, and running a command still go through the [API](/api.md).

<Warning>
  Gateway access is restricted. An API token is accepted only when the account has developer access.

  Send a short description of your use case to [support@fnlb.net](mailto:support@fnlb.net). Access is not enabled without that approval.
</Warning>

## Two ways to read it

1. **REST**, documented in the [gateway reference](/gateway.md) and explained in [REST interface](/gateway/rest-interface#authentication). Use this when you want the current party, presence, or shard list.
2. The lists only include bots with a live connection. An offline bot still appears in [GET /bots](/api?method=GET&path=/bots) on the API, and it does not appear here.

Polling the gateway also keeps you off the API routes that manage bots. The two services have separate [rate limits](/docs/rate-limits.md#gateway).

## Match the API ids

The gateway does not have its own bot ids.

- `{botId}` is `id` from [GET /bots](/api?method=GET&path=/bots).
- `FNLB_BUCKET_ID` is `id` from [GET /user](/api?method=GET&path=/user), or `sub` from [GET /oauth2/userinfo](/api?method=GET&path=/oauth2/userinfo).
- A shard's `categories` are the same category ids as [GET /categories](/api?method=GET&path=/categories) and the SDK `categories` array.
- `clusterName` is the name you passed to the [SDK](/docs/sdk-node.md) or `CLUSTER_NAME` in [self-hosting](/self-hosting-guide).

Run a command on the API, then read [GET /bots/{botId}](/gateway?method=GET&path=/bots/{botId}) if you need the party that command changed. The command response itself is only the bot's text reply.

## What people use it for

- A dashboard of bots that are online, booting, or busy.
- Party members, outfits, and who is the leader.
- Shard health: how many bots a cluster was asked to run, and how many are connected.

## Next

<CardGroup cols={2}>
  <Card icon="http" href="/gateway/rest-interface#authentication" title="REST interface">
    The base URL, the account id parameter, and the status values.
  </Card>
  <Card icon="gateway" href="/gateway" title="Gateway reference">
    Every route, with fields and the try client.
  </Card>
</CardGroup>