GitHub Live Demo Rate Limiting Endpoints Languages Config CLI

OpenRLApi

Self-contained, high-performance, open-source Rocket League item catalog, metadata, player title, and asset API. Extracts UPK binaries and decrypted Coalesced files, parses game metadata, and delivers endpoints with zero-copy in-memory gzip caching.

VelocityRL Integration: OpenRLApi is used by the VelocityRL project to power item catalogs, paint finishes, certifications, player titles, and asset previews.

Features

Interactive Demo & Quickstart

You can try out OpenRLApi through the public live demo or run a local instance.

Live Demo

Local Demo Setup

# Option 1: Docker
git clone https://github.com/bitsfdb/OpenRLApi.git
cd OpenRLApi
docker compose up -d

# Option 2: Local Python
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -e .
openrlapi serve --port 8000

Once started, open http://localhost:8000/docs to test endpoints interactively.

Demo cURL Commands

# 1. Check API status and catalog counts
curl -s "https://api.velocityrl.tech/health"

# 2. Query Goldstone wheels in Spanish (item ID 358)
curl -s "https://api.velocityrl.tech/v2/rl/products/358?l=ESN"

# 3. Search items with pagination
curl -s "https://api.velocityrl.tech/v2/rl/products?search=Octane&limit=3"

# 4. Query PsyNet title with custom colors & glow in Spanish
curl -s "https://api.velocityrl.tech/v2/rl/titles/CRL_Analyst?l=ESN"

# 5. Fetch full pre-compressed catalog via Gzip
curl -s "https://api.velocityrl.tech/items.json?l=INT" -H "Accept-Encoding: gzip" --output items.json.gz

API Rate Limiting

To protect service stability and ensure fair consumption, OpenRLApi implements an in-memory sliding-window IP rate limiter (RateLimiterMiddleware).

Setting Value Description
Default Rate Limit 300 req / min Max requests allowed per 60-second sliding window per IP. Configurable via OPENRL_RATE_LIMIT.
Exempt Endpoints /, /health Health checks and root probe routes bypass rate limiting.
IP Resolution CF-Connecting-IP, X-Forwarded-For Detects genuine client IP behind Cloudflare or reverse proxies, falling back to socket IP.
Exceeded Status HTTP 429 Too Many Requests Returns JSON: {"detail": "Rate limit exceeded"}.

Consumption Guidelines

API Endpoints Reference

Method Endpoint Query Params Description
GET /health — Service health, item counts, title counts, and build version
GET /items.ver — Current game version manifest hash string (e.g. 260825.79374.526531)
GET /items.json
/v2/rl/items.json		 l, lang Master catalog (~29 MB) with instant Level-9 gzip delivery
GET /v2/rl/products search, category, l, limit, offset, full, all Paginated products list with search and category filters
GET /v2/rl/products/{id} l, lang, full Single item by ID (e.g. 358)
GET /titles.json
/v2/rl/titles.json		 l, lang Master player titles catalog from PsyNet with in-memory gzip
GET /v2/rl/titles category, search, has_glow, has_color, l, limit, offset, full Paginated titles with color and glow metadata
GET /v2/rl/titles/{id} l, lang, full Single player title by ID or text
GET /v2/rl/titles/categories — Title categories and styling defaults
GET /v2/rl/categories — Item categories with counts
GET /v2/rl/attributes — Paint finishes and certifications dictionaries
GET /thumbnails/{file}.png — Static item thumbnail renders (cached 30 days)
POST /v2/rl/refresh — Triggers catalog re-read and in-memory cache regeneration

Language Localization

Pass the language code in the ?l= or ?lang= parameter. All 12 game languages are fully supported:

Configuration

Variable Default Description
OPENRL_HOST 0.0.0.0 Bind host address
OPENRL_PORT 8000 Bind port
OPENRL_WORKERS 1 Uvicorn worker count
OPENRL_RATE_LIMIT 300 Rate limit per minute per client IP
OPENRL_DATA_DIR ./data Directory storing JSON databases
OPENRL_THUMBNAILS_DIR ./thumbnails Directory for extracted PNG thumbnails
COALESCED_AES_KEY 14wySp... (Static) Static AES key built into the codebase; universal and identical across all game installations and platforms.

CLI Commands

# Run API server
openrlapi serve [--host 0.0.0.0] [--port 8000] [--workers 4]

# Extract items and translations from game packages
openrlapi extract [--upk TAGame.upk] [--coalesced CookedPCConsole/]

# Sync player titles from PsyNet
openrlapi sync-titles [--build-id ID]

# Extract PNG thumbnails from UPKs via umodel
openrlapi extract-thumbs [--cooked-dir DIR] [--out DIR]

# Run preserving updater against Epic CDN
openrlapi update [--app Sugar]