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

# FNLB Gateway REST API

> REST interface for retrieving real-time state information about FNLB bots and gateway shards, including connected bots, party data, and shard/cluster health.

The Gateway API provides a REST surface for **real-time state** information about connected bots and gateway shards. For low-latency streaming events, use the Gateway WebSocket (not covered here). The REST endpoints are useful for polling current state.

<Warning>
  Looking for the full API Reference? Visit [api-docs.fnlb.net/gateway/](https://api-docs.fnlb.net/gateway/) for our comprehensive interactive documentation.
</Warning>

Common use cases:

* Show which bots are currently connected.
* Display party members and presence status.
* Inspect shard / cluster health and capacity.

## Base URL

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

<Info>
  All endpoints require a valid API key provided in the `Authorization` header using your FNLB API token. [Learn more.](/authenticating)
</Info>

<Warning>
  All requests **must** include the `FNLB_BUCKET_ID` query parameter using your FNLB account ID.\
  Example: `https://gateway.fnlb.net/bots?FNLB_BUCKET_ID=62e542d92a56e7ebd885a9d2`
</Warning>

***

## Endpoints

### GET /bots

Returns a list of **currently connected bots**. This endpoint is read-only and only includes bots with an active connection to the gateway (it does not list offline bots).

**Request**

```
GET https://gateway.fnlb.net/bots
Accept: application/json
```

**Response (200 OK)**

<ResponseField name="response" type="array" required>
  An array of connected bot objects.
</ResponseField>

Each bot object contains the most relevant public state fields. Common fields are documented below.

<ResponseField name="id" type="string" required>
  Unique identifier for the bot.
</ResponseField>

<ResponseField name="nickname" type="string" required>
  Nickname of the bot.
</ResponseField>

<ResponseField name="email" type="string">
  Email address associated with the bot account (where applicable).
</ResponseField>

<ResponseField name="status" type="number" required>
  Numeric status code describing connection state.\
  `Offline: 0, Booting: 1, Available: 2, Busy: 3, Disconnected: 4`
</ResponseField>

<ResponseField name="epicId" type="string">
  Epic account id.
</ResponseField>

<ResponseField name="friendsCount" type="number">
  Number of friends currently known for the bot.
</ResponseField>

<ResponseField name="presenceStatus" type="string">
  Short presence string that may include the custom status.
</ResponseField>

<ResponseField name="party" type="object">
  Party information when the bot is currently in a party. If the bot is not in a party this field may be omitted.
</ResponseField>

<ResponseField name="party.id" type="string">
  Party unique id.
</ResponseField>

<ResponseField name="party.playlistId" type="string">
  Optional playlist or game mode id for the party.
</ResponseField>

<ResponseField name="party.members" type="array">
  List of party members with their in-party metadata.
</ResponseField>

<ResponseField name="party.members[].id" type="string" required>
  Member account id.
</ResponseField>

<ResponseField name="party.members[].displayName" type="string">
  Member display name.
</ResponseField>

<ResponseField name="party.members[].outfit" type="string">
  Cosmetic outfit identifier for the member.
</ResponseField>

<ResponseField name="party.members[].backpack" type="string">
  Cosmetic backpack identifier.
</ResponseField>

<ResponseField name="party.members[].pickaxe" type="string">
  Cosmetic pickaxe/harvest tool identifier.
</ResponseField>

<ResponseField name="mmsBannedUntil" type="number">
  Optional timestamp (ms since epoch) when an matchmaking ban expires.
</ResponseField>

**Example response (200)**

```json theme={null}
[
  {
    "id": "664c91348d12740f67776132",
    "nickname": "Alpha Bot",
    "email": "alpha-bot@example.com",
    "status": 1,
    "epicId": "66c4b21ecaed451e9f6444d3842954a2",
    "friendsCount": 5,
    "presenceStatus": "1/16 | BL | fnlb.net",
    "party": {
      "id": "a05e8408078e4df3b4ff366a0305a402",
      "playlistId": "Playlist_DefaultDuo",
      "members": [
        {
          "id": "e33a89ac51dc413a9414e3b941284bcf",
          "displayName": "Alpha",
          "outfit": "CID_434_Athena_Commando_F_StealthHonor",
          "backpack": "BID_138_Celestial",
          "pickaxe": "Pickaxe_ID_116_Celestial",
          "variants": {},
          "isReady": false,
          "isLeader": true,
          "isSittingOut": false,
          "isPlaying": false
        }
      ]
    }
  },
  {
    "id": "664c91348d12740f67776133",
    "nickname": "Beta Bot",
    "email": "beta-bot@example.com",
    "status": 2,
    "epicId": "66c4b21ecaed451e9f6444d3842954a3",
    "friendsCount": 0,
    "party": null
  }
]
```

### GET /shards

Returns metadata about connected gateway shards (clusters). Useful for monitoring cluster capacity and which shard a bot is served from.

**Request**

```
GET https://gateway.fnlb.net/shards
Accept: application/json
```

**Response (200 OK)**

<ResponseField name="response" type="array" required>
  Array of shard status objects.
</ResponseField>

Common fields returned for each shard:

<ResponseField name="id" type="string" required>
  Shard unique identifier.
</ResponseField>

<ResponseField name="clusterId" type="string" required>
  Logical cluster id.
</ResponseField>

<ResponseField name="clusterName" type="string">
  Human-friendly cluster name.
</ResponseField>

<ResponseField name="version" type="string">
  Bot version running on the shard.
</ResponseField>

<ResponseField name="requestedBots" type="number">
  Number of bots requested/allocated to this shard.
</ResponseField>

<ResponseField name="connectedBots" type="number" required>
  Current number of connected bots on this shard.
</ResponseField>

<ResponseField name="categories" type="array">
  Optional array of category ids associated with the shard.
</ResponseField>

<ResponseField name="bots" type="array">
  Optional array of bot ids the shard was started with.
</ResponseField>

<ResponseField name="isOutdated" type="boolean">
  If true, the shard is running an older bot version.
</ResponseField>

<ResponseField name="isManaged" type="boolean">
  Whether this shard is VIP.
</ResponseField>

<ResponseField name="platform" type="string">
  OS/platform string (e.g. "Linux").
</ResponseField>

<ResponseField name="appSource" type="string">
  The deployment source (e.g. "SelfHosted" or an internal name).
</ResponseField>

**Example response (200)**

```json theme={null}
[
  {
    "id": "nXvJvQt5l02MITpMAAAb",
    "clusterId": "public-cluster",
    "clusterName": "Public Cluster",
    "version": "1.2.3",
    "requestedBots": 20,
    "connectedBots": 3,
    "categories": ["66c4b21ecaed451e9f6444d3842954a7"],
    "isManaged": false,
    "isOutdated": false,
    "platform": "Linux",
    "appSource": "SelfHosted"
  },
  {
    "id": "wGOaMRh3YZVf-J3CAANn",
    "clusterId": "vip-cluster",
    "clusterName": "VIP Cluster",
    "version": "1.2.3",
    "requestedBots": 10,
    "connectedBots": 0,
    "categories": ["66c4b21ecaed451e9f6444d3842954a7"],
    "isManaged": true,
    "isOutdated": false,
    "platform": "Linux",
    "appSource": "SelfHosted"
  }
]
```

## Notes & Best Practices

* These REST endpoints reflect *currently connected* state. They are useful for polling, for real-time events prefer the gateway WebSocket.
* Keep polling intervals reasonable (10-30s).

<Warning>
  Looking for the full API Reference? Visit [api-docs.fnlb.net/gateway/](https://api-docs.fnlb.net/gateway/) for our comprehensive interactive documentation.
</Warning>