---
title: "Gateway REST Interface"
description: "Read connected bots, parties, and shards."
canonical: "https://developers.fnlb.net/docs/gateway-rest"
markdown: "/docs/gateway-rest.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 REST Interface

The gateway REST API returns **current** state. Field lists live on each route in the [gateway reference](/gateway.md), which is generated from the same service. This page covers the rules those routes share.

Base URL:

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

## Authentication

Send the same `Authorization` header as the [API](/docs/authenticating.md). The gateway accepts:

- an API token, only if the account has developer access
- an OAuth2 access token with the `bots.read` scope

A session from the website is not accepted here. Use **Try request** in the reference only when that client can send one of the tokens above.

<Warning>
  Every request must include `FNLB_BUCKET_ID`, and it must be your FNLB account id. Any other value returns `403`.
</Warning>

```bash
curl "https://gateway.fnlb.net/v1/bots?FNLB_BUCKET_ID=YOUR_ACCOUNT_ID" \
  -H "Authorization: Bearer FNLB_YOUR_API_TOKEN"
```

Your account id is the `id` from [GET /user](/api?method=GET&path=/user).

## Routes

<CardGroup cols={2}>
  <Card icon="gateway" href="/gateway?method=GET&path=/bots" title="GET /bots">
    Every bot connected to the gateway for this account.
  </Card>
  <Card icon="gateway" href="/gateway?method=GET&path=/bots/{botId}" title="GET /bots/{botId}">
    One connected bot, including its party when it has one.
  </Card>
  <Card icon="server" href="/gateway?method=GET&path=/shards" title="GET /shards">
    Clusters serving those bots, with capacity and version.
  </Card>
</CardGroup>

`GET /bots` is not the catalog of bots you own. Offline bots are omitted. Use [GET /bots on the API](/api?method=GET&path=/bots) for that list.

## Status

`status` on a bot is a number:

| Value | State |
| :--- | :--- |
| `0` | Offline |
| `1` | Booting |
| `2` | Available |
| `3` | Busy |
| `4` | Disconnected |

## Party member flags

When `party` is present, each member has a `flags` bitfield:

| Bit | Meaning |
| :--- | :--- |
| `1` | Ready |
| `2` | Leader |
| `4` | Sitting out |
| `8` | Playing |

The boolean fields `isReady`, `isLeader`, `isSittingOut`, and `isPlaying` are still sent. Prefer `flags`. The booleans will be removed later.

## Polling

Stay inside the [gateway limits](/docs/rate-limits.md): 100 requests per 10 seconds for the whole gateway, 100 per minute shared by the bot routes, and 100 per minute for shards. A dashboard can refresh every 10 to 30 seconds.

<Card icon="gateway" href="/gateway" title="Open the gateway reference">
  Schemas, examples, and errors for each route.
</Card>