FreeScript
cfx-api
by pablo-1610 · version 2026.10.20 · updated 3 days ago
No reviews yet
- Downloads
- 0
- Reviews
- 0
- Size
- 77 KB
- Code check
- Clean
- Licence
- MIT
- Released
- Nov 2026
Fully typed Node.js/TypeScript library to read the Cfx.re, FiveM and RedM server list, single servers, featured servers, icons, status and direct game server da
cfx-api
The fastest way to read the Cfx.re, FiveM and RedM server list from Node.js.
Table of contents
Quick start
API
The library exposes two namespaces,
servers**
Fetches the full public server list and decodes it. Returns an array of
Filter, Type, Description
**
Fetches a single server by its join id. Returns a
**
Fetches the featured servers shown on the official server list. Returns a
**
Fetches the server icon as a
**
Queries a game server directly through its own endpoints, using an
status**
Returns a
**
Returns the unresolved incidents.
Aliases
Recipes
Total players online across the whole network
Top 10 servers by player count
Find roleplay servers in a given language with free slots
Check whether a player is connected to a server
The CitizenServer model
A decoded server exposes the following members.
Member, Description
…
The fastest way to read the Cfx.re, FiveM and RedM server list from Node.js.
cfx-api lets you query the public Cfx.re infrastructure with a clean, fully typed API: the complete server list (decoded from the binary streamRedir feed), a single server, featured servers, server icons, the Cfx.re status page, and a game server's own endpoints.Table of contents
- Features
- Installation
- Quick start
- API
- servers
- status
- Aliases
- The CitizenServer model
- License
- 🌍 Full server list decoded from the protobuf
streamRedirfeed, with client-side filters. - 🔎 Single server lookup with the complete payload (players, resources, owner, variables…).
- ⭐ Featured servers as shown on the official server list.
- 🖼️ Server icons as a
Bufferor a ready-to-use URL. - 🛰️ Direct game server queries (
info.json,dynamic.json,players.json). - 📊 Cfx.re status and unresolved incidents.
- 🧩 Fully typed, zero configuration, works in JavaScript and TypeScript.
npm i cfx-apiQuick start
const cfx = require("cfx-api")
;(async () => {
const servers = await cfx.servers.all({ minPlayers: 1, limit: 50 })
console.log(`${servers.length} servers fetched`)
const status = await cfx.status.get()
console.log(status.everythingOk ? "All systems operational" : "Cfx.re is experiencing issues")
})()
import { servers, status } from "cfx-api"API
The library exposes two namespaces,
servers and status. Standalone fetch* functions are also available as aliases.servers**
servers.all(filters?)**Fetches the full public server list and decodes it. Returns an array of
CitizenServer.
const list = await cfx.servers.all({
locale: "en-US",
gametype: "Roleplay",
minPlayers: 10,
maxPlayers: 1000,
tag: "drift",
onlyOpen: true,
search: "my community",
limit: 100,
})Filter, Type, Description
locale, string, Keep only servers using this localegametype, string, Keep only servers with this game typemapname, string, Keep only servers with this map nameminPlayers, number, Minimum connected playersmaxPlayers, number, Maximum connected playerstag, string, Keep only servers exposing this tagonlyOpen, boolean, Exclude full serverssearch, string, Case-insensitive match on the hostnamelimit, number, Stop after this many matching servers**
servers.single(id)**Fetches a single server by its join id. Returns a
CitizenServer.
const server = await cfx.servers.single("xxxxxx")
console.log(server.hostname, server.playersCount, server.maxPlayers)**
servers.featured()**Fetches the featured servers shown on the official server list. Returns a
CfxFeaturedServers.
const featured = await cfx.servers.featured()
console.log(featured.homePageServer.name)
console.log(featured.allIds)**
servers.icon(id, iconVersion) and servers.iconUrl(id, iconVersion)**Fetches the server icon as a
Buffer, or builds its URL.
const server = await cfx.servers.single("xxxxxx")
const icon = await cfx.servers.icon(server.id, server.iconVersion)
const url = cfx.servers.iconUrl(server.id, server.iconVersion)**
servers.info(address), servers.dynamic(address), servers.players(address)**Queries a game server directly through its own endpoints, using an
ip:port address.
const dynamic = await cfx.servers.dynamic("127.0.0.1:30120")
const players = await cfx.servers.players("127.0.0.1:30120")
const info = await cfx.servers.info("127.0.0.1:30120")status**
status.get()**Returns a
CfxStatus.
const status = await cfx.status.get()
console.log(status.level, status.description, status.everythingOk)
const components = await status.fetchComponents()
for (const component of components) {
console.log(`${component.name}: ${component.status}`)
}**
status.unresolvedIncidents()**Returns the unresolved incidents.
const incidents = await cfx.status.unresolvedIncidents()
console.log(incidents.incidents.length)Aliases
cfx.fetchServer(id)
cfx.fetchAllServers(filters)
cfx.fetchFeaturedServers()
cfx.fetchServerIcon(id, iconVersion)
cfx.fetchStatus()
cfx.fetchUnresolvedIncidents()Recipes
Total players online across the whole network
const all = await cfx.servers.all()
const players = all.reduce((sum, server) => sum + server.playersCount, 0)
console.log(`${all.length} servers, ${players} players online`)Top 10 servers by player count
const all = await cfx.servers.all({ minPlayers: 1 })
const top = all.sort((a, b) => b.playersCount - a.playersCount).slice(0, 10)
top.forEach((s) => console.log(`${s.playersCount}/${s.maxPlayers} - ${s.hostname}`))Find roleplay servers in a given language with free slots
const servers = await cfx.servers.all({
locale: "fr-FR",
gametype: "Roleplay",
onlyOpen: true,
})Check whether a player is connected to a server
const server = await cfx.servers.single("xxxxxx")
console.log(server.isPlayerOnline("PlayerName"))The CitizenServer model
A decoded server exposes the following members.
Member, Description
id, Join idhostname, Display nameplayersCount / maxPlayers, Connected players and slot countplayers, Connected playersgameType / mapName, Game type and mapresources, Loaded resourcesserverVersion, Server buildpublicVariables, Raw server variablestags, Parsed tagsconnectedEndpoints / connectEndpoint, Connection endpointsupvotePower / burstPower, Listing power valuesiconVersion / iconUrl, Server iconownerId / ownerName / ownerProfileUrl / ownerAvatarUrl, Owner informationlocale, Server localejoinUrl, cfx.re/join linkisFiveM / isRedM, Platform helpersisFull, Whether the server is fullisOneSyncEnabled, OneSync stateprojectName / projectDesc, Project metadatabannerConnecting / bannerDetail,…