ERLC API Client

ERLC API Client is an enterprise-grade Node.js client for the Emergency Response: Liberty City (ER:LC) API. It offers:

• Built-in rate limiting with an easy-to-use wrapper.
• Comprehensive command validation.
• Real-time monitoring.

Installation

Install the package using npm:

npm install erlc-api-client

Authentication

Initialize the client by providing your API key. Optionally, you can include a global key for increased rate limits:

const ERLCClient = require("erlc-api-client");

const client = new ERLCClient({
  SERVER_KEY: "your_api_key", // Required for server access
  GLOBAL_KEY: "optional_global_key", // For increased rate limits (available to global key program participants)
});

Rate Limits

🚨 Rate Limits
Rate limits are enforced across the PRC API to prevent spam, abuse, and service disruptions caused by overloads. These limits apply on a per global API key basis, and—if no global key is provided—per IP address.

Definitions

• Application: An application (such as a Discord bot or website) that accesses the PRC API. Each application is uniquely identified by its application key, which is provided in the Authorization header.
• Server: A private server uniquely identified by its server key, provided via the Server-Key header.

Global Rate Limit

Each application is restricted to a set number of requests per second. The exact limit may vary per application and server, so it's essential to use the rate limit headers in each response to dynamically adjust your request rate.

Per-Route Rate Limit

Certain routes, especially those that are more intensive or prone to abuse, have their own rate limits. These per-route limits are identified by the X-RateLimit-Bucket header. For example, the POST route to send a command to an ER:LC server is limited to 1 request every 5 seconds (subject to change), and this bucket is labeled as command-[Server-Key].

Rate Limit Headers

For most API requests, you will see the following headers (example values provided; do not hardcode these):

| Header | Example Value | Description | | ----------------------- | ----------------- | ------------------------------------------------------------------- | | X-RateLimit-Bucket | global | Indicates the rate limit bucket the request was subject to | | X-RateLimit-Limit | 35 | Maximum number of requests allowed in the current rate limit bucket | | X-RateLimit-Remaining | 34 | Remaining requests available before hitting the limit | | X-RateLimit-Reset | Epoch Timestamp | Epoch timestamp indicating when the rate limit will reset |

When You Are Rate Limited

If you exceed a rate limit, you will receive an HTTP 429 response. The response body will include:

• A message indicating the error.
• A retry_after field (in seconds) specifying how long to wait before retrying.
• The rate limit bucket that was exceeded.

Normal rate limit headers will also be included in the response.

Repeat Offenders

Clients that repeatedly exceed the rate limit (i.e., after receiving multiple 429 responses) may be blocked for extended periods. Always respect the retry_after header and the response message to avoid longer blocks.

Invalid Requests

Be cautious: repeatedly sending requests with invalid server keys can result in a permanent IP block. As a best practice, if you receive a 403 error, stop using that server key, as it has likely been regenerated by the server owner.

For detailed information on rate limits, please refer to the PRC Rate Limits Documentation.

Basic Usage

When connecting to the API, the response is returned in JSON format. For example, connecting to the server yields a response like:

{
  "Name": "API Test",
  "OwnerId": 1,
  "CoOwnerIds": [1],
  "CurrentPlayers": 1,
  "MaxPlayers": 1,
  "JoinKey": "APIServer",
  "AccVerifiedReq": "Disabled / Email / Phone/ID",
  "TeamBalance": true
}

Example code to connect and log the server name:

client
  .connect()
  .then((serverInfo) => console.log(`Connected to ${serverInfo.Name}`))
  .catch((err) => console.error("Connection failed:", err.message));

API Endpoints

All API methods return Promises with JSON responses. Here are some examples:

Get Server Information

const info = await client.server.getInfo();

Example response:

{
  "Name": "API Test",
  "OwnerId": 1,
  "CoOwnerIds": [1],
  "CurrentPlayers": 1,
  "MaxPlayers": 1,
  "JoinKey": "APIServer",
  "AccVerifiedReq": "Disabled / Email / Phone/ID",
  "TeamBalance": true
}

Get Online Players

const players = await client.server.getPlayers();

Example response:

[
  {
    "Player": "PlayerName:Id",
    "Permission": "Normal / Server Administrator / Server Owner / Server Moderator",
    "Callsign": "The player's callsign",
    "Team": "The player's team"
  }
]

Get Join Logs

const joinLogs = await client.server.getJoinLogs();

Example response:

[
  {
    "Join": true,
    "Timestamp": 1704614400,
    "Player": "PlayerName:Id"
  }
]

Additional Endpoints

The API also supports:

• Players in Queue: /server/queue – Returns an array of Roblox IDs.
• Kill Logs: /server/killlogs – Returns an array of kill log objects.
• Command Logs: /server/commandlogs – Returns an array of command log objects.
• Moderator Call Logs: /server/modcalls – Returns moderator call logs.
• Bans: /server/bans – Returns ban details.
• Spawned Vehicles: /server/vehicles – Returns details of vehicles spawned on the server.

For more detailed information on endpoints and their JSON response formats, please see the API Reference Documentation.

Command System

The client includes a built-in command system that executes pre-validated commands directly on the server.

Example commands:

// Send a server-wide message
await client.commands.send(":h Server shutting down soon");

// Change weather to rain
await client.commands.send(":weather rain");

// Ban a player
await client.commands.send(":ban RuleBreaker123");

Supported Commands

| Command | Parameters | Description | | ----------------- | ---------------------------------- | ------------------------------------ | | :h / :hint | <message> | Display a server-wide hint message | | :m / :message | <message> | Display a server-wide message | | :pm | <player> <message> | Send a private message to a player | | :weather | clear/rain/fog/snow/thunderstorm | Change the server weather | | :time | 0-24 | Set the time of day (24-hour format) | | :ban | <player> | Ban a player from the server | | :unban | <player> | Unban a player | | :jail | <player> | Jail a player | | :unjail | <player> | Release a player from jail | | :wanted | <player> | Mark a player as wanted | | :unwanted | <player> | Remove a player's wanted status | | :admin | <player> | Grant admin privileges | | :unadmin | <player> | Revoke admin privileges | | :mod | <player> | Grant moderator privileges | | :unmod | <player> | Revoke moderator privileges | | :helper | <player> | Grant helper privileges | | :unhelper | <player> | Revoke helper privileges | | :kill | <player> | Kill a player | | :heal | <player> | Heal a player | | :respawn | <player> | Respawn a player | | :tp | <player1> <player2> | Teleport one player to another | | :startfire | house/brush/building | Start a fire | | :stopfire | - | Extinguish all fires | | :priority | <seconds> | Set a priority timer |

Notes:

• Player identifiers can be specified as either PlayerName or PlayerName:ID.
• Time values are in 24-hour format (e.g., 0 = midnight).
• Weather options are case-insensitive.

Error Handling

It is recommended to handle errors using try/catch blocks:

try {
  await client.commands.send(":invalid-command");
} catch (err) {
  console.error(err.message); // "Invalid command: :invalid-command"
}

TypeScript Support

The client supports TypeScript out-of-the-box:

import ERLCClient from "erlc-api-client";
const client = new ERLCClient({ API_KEY: "your_api_key" });

License

This project is licensed under the ERLC API Client License (GPL-3.0 with additional restrictions). By using this software, you agree to:

• Not publicly redistribute modified versions.
• Comply with Roblox and PRC Terms of Service.
• Provide proper attribution.

For more detailed information on endpoints and response formats, please refer to the API Reference Documentation.