Skip to main content

Browse Lobbies

Protected Endpoint

This endpoint requires authentication to access. You can learn more about that here.

Quick Usage
GET https://api.clarioncorp.net/v2/customs/browse

This endpoint replies with basic data on every lobby (up to 50 for now) matching the search parameter. If no search parameter is provided, it will just return all of them. Below is an example JSON body you can expect in response.

{
  "lobbies": [
    {
      "lobbyId": "429ed180-219b-4c85-ab71-2d0222ec4714",
      "lobbyName": "blals's Game",
      "ownerUsername": "blals",
      "ownerPlayerId": "6333a58673a37dc7cb11a7a7",
      "currentPlatform": "Steam",
      "platformIds": {
        "discord": {
          "discordId": "246036218566017034",
          "hasFullAccount": true
        }
      },
      "numPlayers": 1,
      "numSpectators": 0,
      "lobbySize": 6,
      "spectatorsAllowed": true,
      "requiresJoinCode": true,
      "serverRegion": "us-east-2",
      "createdTimestamp": "2025-12-20T10:21:59.422Z",
      "gameOptions": {
        "gameFormatId": "GFD_Ranked",
        "mapAssetName": "GMD_AhtenCity",
        "terrainAssetName": "GTD_AhtenCity",
        "modifierAssetName": "OMD_Empty"
      }
    }
  ]
}

All dates are in ISO-8601, and in the UTC timezone.

Example​

Here's an example of a fetch in Typescript:

type BrowseCustomLobby = {
  lobbyId: string,
  lobbyName: string,
  ownerUsername: string,
  ownerPlayerId: string,
  currentPlatform: string, // like 'Steam'
  platformIds: {
    discord?: {
      discordId: string,
      hasFullAccount: boolean
    }
  },
  numPlayers: number,
  numSpectators: number,
  lobbySize: number,
  spectatorsAllowed: boolean,
  requiresJoinCode: boolean, // a.k.a. "isPrivate"
  serverRegion: string, // e.g. "us-east-2"
  createdTimestamp: Date,
  gameOptions: {
    gameFormatId: string,
    mapAssetName: string,
    terrainAssetName: string,
    modifierAssetName: string,
  }
}

async function fetchLobbies(search: string): Promise<BrowseCustomLobby[]> {
  try {
    const response = await fetch(`https://api.clarioncorp.net/v2/customs/browse?search=${search}`, {
      method: 'GET',
      headers: { 'Authorization': `Bearer ${process.env.PRIVATE_CC_TOKEN}` }, // use your own
      cache: 'no-store',
    });

    const data = await response.json();

    return data.lobbies; // returns array list of them

    // if you want only the first one, do this instead:
    // return data.lobbies[0];
  } catch (error) {
    console.error(`There was a problem fetching custom lobbies from ClarionCorp!`, error);
  }
}