PythonPRC

An async Python wrapper for the PRC Private Server API — the API for ER:LC private servers.

Installation

pip install pythonprc

For webhook signature verification, you'll also need cryptography (installed by default) or optionally PyNaCl:

pip install "pythonprc[nacl]"

Quickstart

import asyncio
from pythonprc import PythonPRC

async def main():
    client = PythonPRC("your-server-key")

    info = await client.get_server(players=True)
    print(f"{info.name}: {info.current_players}/{info.max_players} players")

    for player in info.players:
        print(player.username, player.team, player.location)

asyncio.run(main())

Authentication

All requests require a server key, obtained from your private server's settings in-game (Settings → search "API key"). Pass it as the first argument to PythonPRC.

If you have a global API key (issued by PRC for large-scale apps), pass it as global_api_key:

client = PythonPRC("your-server-key", global_api_key="your-global-key")

Client

PythonPRC(
    server_key: str,
    global_api_key: str | None = None,
    max_retries: int = 3,       # retries on 5xx / connection errors
    backoff_base: float = 1.0,  # base seconds for exponential backoff
)

The client exposes a single low-level method and several high-level convenience methods.

Low-level

await client.request(method, path, **kwargs)

Passes **kwargs directly to aiohttp. Handles rate limiting, backoff, and error raising automatically. Returns the parsed JSON body.

Rate limiting

The client reads X-RateLimit-* headers on every response and tracks state per bucket. If a bucket is exhausted it will proactively sleep before the next request rather than hitting a 429. On a 429 it raises RateLimitError with retry_after and bucket attributes.

Methods

get_server(**flags) → ServerInfo

Fetches server status. All sub-resources are opt-in:

info = await client.get_server(
    players=True,
    staff=True,
    join_logs=True,
    queue=True,
    kill_logs=True,
    command_logs=True,
    mod_calls=True,
    emergency_calls=True,
    vehicles=True,
)

Only request what you need — each flag adds data to the response.

send_command(command: str) → str

Runs a command in-game as virtual server management. Returns the API's confirmation message.

await client.send_command(":h Welcome to the server!")
await client.send_command(":kick Username Reason")

Convenience methods

Each of these calls get_server with the relevant flag and returns the list directly:

await client.get_players()         # list[Player]
await client.get_staff()           # list[StaffMember]
await client.get_join_logs()       # list[JoinLogEntry]
await client.get_queue()           # list[int]  (Roblox user IDs)
await client.get_kill_logs()       # list[KillLogEntry]
await client.get_command_logs()    # list[CommandLogEntry]
await client.get_mod_calls()       # list[ModCall]
await client.get_emergency_calls() # list[EmergencyCall]
await client.get_vehicles()        # list[Vehicle]

Models

ServerInfo

Player

PlayerLocation

StaffMember

Vehicle

JoinLogEntry

KillLogEntry

CommandLogEntry

ModCall

EmergencyCall

Enums

Team

Civilian, Sheriff, Police, Fire, DOT, Unknown

Permission

Normal, Moderator, Admin, Server Owner, Unknown

Errors

All errors inherit from ERLCError.

from pythonprc import PythonPRC
from pythonprc.errors import RateLimitError, ServerOfflineError

try:
    await client.send_command(":shutdown")
except ServerOfflineError:
    print("No players in server")
except RateLimitError as e:
    print(f"Rate limited, retry in {e.retry_after}s")

Webhooks

ER:LC can POST events to your endpoint. Every request is signed with Ed25519 and must be verified before acting on it.

Currently sent events: messages starting with ; (custom in-game commands) and emergency calls.

from pythonprc.webhook import verify_signature, WebhookVerificationError

# aiohttp example
async def handle_webhook(request):
    raw_body = await request.read()
    try:
        verify_signature(
            timestamp=request.headers["X-Signature-Timestamp"],
            sig_hex=request.headers["X-Signature-Ed25519"],
            raw_body=raw_body,
        )
    except WebhookVerificationError:
        raise web.HTTPUnauthorized()

    payload = await request.json()
    ...

To set up your webhook URL, go to your private server settings and search for Event Webhook. Paste an HTTPS URL that can receive JSON POST requests. Append ?long=true to receive extended payloads with type information.

License

GPL-3.0-only — see LICENSE.

pythonprc is not affiliated with or endorsed by PRC or the ER:LC team.