FNLB Gateway REST API

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.

Looking for the full API Reference? Visit api-docs.fnlb.net/gateway/ for our comprehensive interactive documentation.

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

All endpoints require a valid API key provided in the Authorization header using your FNLB API token. Learn more.

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

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)

array

required

An array of connected bot objects.

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

string

required

Unique identifier for the bot.

string

required

Nickname of the bot.

string

Email address associated with the bot account (where applicable).

number

required

Numeric status code describing connection state.
Offline: 0, Booting: 1, Available: 2, Busy: 3, Disconnected: 4

string

Epic account id.

number

Number of friends currently known for the bot.

string

Short presence string that may include the custom status.

object

Party information when the bot is currently in a party. If the bot is not in a party this field may be omitted.

string

Party unique id.

string

Optional playlist or game mode id for the party.

array

List of party members with their in-party metadata.

string

required

Member account id.

string

Member display name.

string

Cosmetic outfit identifier for the member.

string

Cosmetic backpack identifier.

string

Cosmetic pickaxe/harvest tool identifier.

number

Optional timestamp (ms since epoch) when an matchmaking ban expires.

Example response (200)

[
  {
    "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)

array

required

Array of shard status objects.

Common fields returned for each shard:

string

required

Shard unique identifier.

string

required

Logical cluster id.

string

Human-friendly cluster name.

string

Bot version running on the shard.

number

Number of bots requested/allocated to this shard.

number

required

Current number of connected bots on this shard.

array

Optional array of category ids associated with the shard.

array

Optional array of bot ids the shard was started with.

boolean

If true, the shard is running an older bot version.

boolean

Whether this shard is VIP.

string

OS/platform string (e.g. “Linux”).

string

The deployment source (e.g. “SelfHosted” or an internal name).

Example response (200)

[
  {
    "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).

Looking for the full API Reference? Visit api-docs.fnlb.net/gateway/ for our comprehensive interactive documentation.

Getting Started

API

Gateway

Self Hosting

Base URL

Endpoints

GET /bots

GET /shards

Notes & Best Practices

​Base URL

​Endpoints

​GET /bots

​GET /shards

​Notes & Best Practices

Base URL

Endpoints

GET /bots

GET /shards

Notes & Best Practices