# cfx-api

> JS/TS library to interact with the Cfx.re, FiveM and RedM APIs

Latest version **2.0.1** (published 2026-06-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install cfx-api
pnpm add cfx-api
yarn add cfx-api
bun add cfx-api
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2026-06-28 |
| First published | 2022-07-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 2 |
| Unpacked size | 112.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 52 |
| Author | PABLO-1610 |
| Maintainers | pablo_1610 |
| Keywords | fivem, api, node, fivem-api, cfx, cfx-api, cfx.re, redm, server-list |

## Links

- npm: https://www.npmjs.com/package/cfx-api
- Repository: https://github.com/pablo-1610/cfx-api
- Homepage: https://github.com/pablo-1610/cfx-api#readme
- Issues: https://github.com/pablo-1610/cfx-api/issues
- npm.io page: https://npm.io/package/cfx-api

## Dependencies (2)

- [axios](https://npm.io/package/axios.md) ^1.18.1
- [protobufjs](https://npm.io/package/protobufjs.md) ^8.6.5

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 2.0.1 (latest) — 2026-06-28
- 2.0.0 — 2026-06-28
- 1.2.31 — 2024-08-21
- 1.2.3 — 2024-08-21
- 1.2.0 — 2024-02-24
- 1.1.0 — 2023-03-14
- 1.0.14 — 2023-01-31
- 1.0.13 — 2022-12-30
- 1.0.122 — 2022-07-22
- 1.0.121 — 2022-07-22
- 1.0.12 — 2022-07-21
- 1.0.11 — 2022-07-20
- 1.0.1 — 2022-07-20
- 1.0.0-alpha.2 — 2022-07-20
- 1.0.0-alpha.1 — 2022-07-20
- … 1 more at https://npm.io/package/cfx-api/versions

## README

<h1 align="center">cfx-api</h1>

<p align="center">
  The fastest way to read the Cfx.re, FiveM and RedM server list from Node.js.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/cfx-api"><img src="https://img.shields.io/npm/v/cfx-api?color=cb3837&logo=npm" alt="npm version"></a>
  <a href="https://www.npmjs.com/package/cfx-api"><img src="https://img.shields.io/npm/dm/cfx-api?color=cb3837&logo=npm" alt="npm downloads"></a>
  <a href="https://github.com/pablo-1610/cfx-api/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/cfx-api?color=blue" alt="license"></a>
  <a href="https://github.com/pablo-1610/cfx-api/stargazers"><img src="https://img.shields.io/github/stars/pablo-1610/cfx-api?style=social" alt="stars"></a>
  <a href="https://github.com/pablo-1610/cfx-api/actions"><img src="https://img.shields.io/github/actions/workflow/status/pablo-1610/cfx-api/unit_tests.yml?branch=master&label=tests" alt="tests"></a>
  <img src="https://img.shields.io/badge/TypeScript-ready-3178c6?logo=typescript&logoColor=white" alt="TypeScript ready">
</p>

<hr>

`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](#features)
- [Installation](#installation)
- [Quick start](#quick-start)
- [API](#api)
  - [servers](#servers)
  - [status](#status)
  - [Aliases](#aliases)
- [The CitizenServer model](#the-citizenserver-model)
- [License](#license)

## Features

- 🌍 **Full server list** decoded from the protobuf `streamRedir` feed, 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 `Buffer` or 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.

## Installation

```bash
npm i cfx-api
```

## Quick start

```js
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")
})()
```

```ts
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`.

```js
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 locale |
| `gametype` | string | Keep only servers with this game type |
| `mapname` | string | Keep only servers with this map name |
| `minPlayers` | number | Minimum connected players |
| `maxPlayers` | number | Maximum connected players |
| `tag` | string | Keep only servers exposing this tag |
| `onlyOpen` | boolean | Exclude full servers |
| `search` | string | Case-insensitive match on the hostname |
| `limit` | number | Stop after this many matching servers |

#### `servers.single(id)`

Fetches a single server by its join id. Returns a `CitizenServer`.

```js
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`.

```js
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.

```js
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.

```js
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`.

```js
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.

```js
const incidents = await cfx.status.unresolvedIncidents()
console.log(incidents.incidents.length)
```

### Aliases

```js
cfx.fetchServer(id)
cfx.fetchAllServers(filters)
cfx.fetchFeaturedServers()
cfx.fetchServerIcon(id, iconVersion)
cfx.fetchStatus()
cfx.fetchUnresolvedIncidents()
```

## Recipes

**Total players online across the whole network**

```js
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**

```js
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**

```js
const servers = await cfx.servers.all({
  locale: "fr-FR",
  gametype: "Roleplay",
  onlyOpen: true,
})
```

**Check whether a player is connected to a server**

```js
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 id |
| `hostname` | Display name |
| `playersCount` / `maxPlayers` | Connected players and slot count |
| `players` | Connected players |
| `gameType` / `mapName` | Game type and map |
| `resources` | Loaded resources |
| `serverVersion` | Server build |
| `publicVariables` | Raw server variables |
| `tags` | Parsed tags |
| `connectedEndpoints` / `connectEndpoint` | Connection endpoints |
| `upvotePower` / `burstPower` | Listing power values |
| `iconVersion` / `iconUrl` | Server icon |
| `ownerId` / `ownerName` / `ownerProfileUrl` / `ownerAvatarUrl` | Owner information |
| `locale` | Server locale |
| `joinUrl` | `cfx.re/join` link |
| `isFiveM` / `isRedM` | Platform helpers |
| `isFull` | Whether the server is full |
| `isOneSyncEnabled` | OneSync state |
| `projectName` / `projectDesc` | Project metadata |
| `bannerConnecting` / `bannerDetail` | Banner URLs |

Helper methods: `hasResource(name)`, `hasAnyResourceStartingWith(prefix)`, `hasTag(tag)`, `isPlayerOnline(name)`.

## License

[MIT](LICENSE) © PABLO-1610

---
_Source: https://npm.io/package/cfx-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._