Developers · API Reference

RIIP Server Intelligence API

A tiered REST API for live Roblox server, discovery, trend, and forecast data. Scoped bearer keys, per-call metering, cursor pagination, and signed webhooks. Base URL https://api.riip.gg/v1.

Get an API key View pricing

Overview

Introduction

The RIIP Server Intelligence API exposes the same live data that powers our Smart Server Finder: ranked live servers, quality-first discovery, momentum trends, and AI occupancy forecasts. Every response is JSON, every call is metered, and every response carries a credits_used field plus rate-limit headers so you always know where you stand.

All requests go to https://api.riip.gg/v1 over HTTPS. The API is versioned in the path — the current version is v1. Breaking changes ship under a new path prefix (e.g. /v2); additive fields are rolled into the current version and are always safe to ignore. We recommend tolerant JSON parsing that ignores unknown fields.

Security

Authentication

Authenticate every request with a bearer API key in the Authorization header: Authorization: Bearer rk_live_.... Keys are scoped — each key carries only the permissions you grant it, and a call to an endpoint outside a key's scope returns 403 forbidden.

Mint keys from the dashboard. The full secret is shown once at creation and stored only as a hash on our side — copy it immediately. To rotate, mint a replacement, deploy it, then revoke the old key; both work during the overlap so you get zero-downtime rotation. Never embed a key in client-side code or commit it to source control; treat rk_live_ keys as production secrets.

authenticate · curl

# Store the key once; never commit it to source control.
export RIIP_KEY="rk_live_7c1f9a..."

curl https://api.riip.gg/v1/servers/find \
  -H "Authorization: Bearer $RIIP_KEY" \
  -G --data-urlencode "game=blade-ball"

Scopes

Scope	Grants
servers:read	Live server discovery, occupancy and health.
discovery:read	Quality-ranked game search and recommendations.
trends:read	Trending and top-games rankings.
forecasts:read	Predicted regional occupancy and demand.
account:read	Read metered usage for the key's account.
webhooks:read	List registered webhook endpoints.
webhooks:write	Register and delete webhook endpoints.

Throughput

Rate limits

Rate limits are enforced per key on a fixed one-minute window and scale with your plan. Every response — success or error — includes the headers below so you can pace requests without guessing.

Plan	Rate limit	Monthly quota	Overage	Includes
Free	60 req/min	1,000 calls/mo	Hard cap — no overage	Server data (servers:read, account:read)
Dev	120 req/min	100,000 calls/mo	$2.00 / 1,000 calls	+ Discovery & webhooks (discovery:read, webhooks:*)
Pro	600 req/min	1,000,000 calls/mo	$1.00 / 1,000 calls	+ Trends, forecasts & analytics (trends:read, forecasts:read)

Response headers

Header	Description
X-RateLimit-Limit	Maximum requests permitted in the current fixed window (per plan).
X-RateLimit-Remaining	Requests still available in the current window.
X-RateLimit-Reset	Unix epoch seconds at which the window resets and Remaining refills.
Retry-After	Seconds to wait before retrying. Present on every 429 and 503 response.

When you exceed the window you get 429 rate_limited with a Retry-After header. Back off using the header value, or exponentially (1s, 2s, 4s, 8s…) with jitter if it is absent, and never retry faster than X-RateLimit-Reset. A sustained overage on the monthly quota also returns 429 rather than silently billing you — you stay in control.

429 Too Many Requests

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1752878520
Retry-After: 18

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 18 seconds."
  }
}

Usage

Metering & billing

Every successful response includes credits_used — the credit cost of that single call. Most reads cost 1 credit; heavier AI endpoints (recommendations, trends, forecasts) cost more, and metering reads like GET /v1/account/usage are free. Credits aggregate into your monthly quota; poll /v1/account/usage for live period totals.

Once you exceed the calls included in your plan, additional calls bill at your plan's overage rate ($2.00/1k on Dev, $1.00/1k on Pro) and appear on the next monthly invoice. The Free plan has no overage — it hard-caps at the quota. For non-idempotent calls (webhook registration), pass an Idempotency-Key header; we de-duplicate retries carrying the same key for 24 hours so a network retry never double-charges or double-creates.

Failure modes

Errors

Errors use standard HTTP status codes and a single JSON envelope. The error.code is a stable machine-readable string; error.message is a human-readable explanation that may change. Branch on code, never on the message text.

error envelope · application/json

{
  "error": {
    "code": "forbidden",
    "message": "Key missing required scope 'trends:read'. Upgrade to the Pro plan to access trends."
  }
}

Status	Code	Meaning
400	bad_request	The request was malformed — bad JSON body, unknown parameter, or wrong value type.
401	unauthorized	The Authorization header is missing, malformed, or the key was revoked.
403	forbidden	The key is valid but lacks the required scope, or the resource belongs to another account.
404	not_found	No resource matches the path — an unknown server_id, game slug, or webhook id.
422	unprocessable_entity	Syntactically valid but semantically rejected — e.g. horizon_days above the allowed maximum.
429	rate_limited	The per-minute rate limit or the monthly quota was exceeded. Honor Retry-After.
500	internal_error	An unexpected error on our side. Safe to retry idempotent (GET) calls with backoff.
503	service_unavailable	A dependency is degraded or the API is in maintenance. Retry after the Retry-After delay.

Collections

Pagination

List endpoints are cursor-paginated. Pass limit to size a page and read next_cursor from the response; feed it back as the cursor parameter to fetch the following page. Cursors are opaque, stable, and safe to hold across requests. When next_cursor is null you have reached the last page.

paginate · curl

# First page
curl https://api.riip.gg/v1/discovery/search \
  -H "Authorization: Bearer $RIIP_KEY" \
  -G --data-urlencode "q=tower defense" --data-urlencode "limit=20"

# Next page — pass the previous response's next_cursor
curl https://api.riip.gg/v1/discovery/search \
  -H "Authorization: Bearer $RIIP_KEY" \
  -G --data-urlencode "q=tower defense" \
     --data-urlencode "limit=20" \
     --data-urlencode "cursor=eyJvIjoyMCwicSI6InRvd2VyIn0"

Reference

Endpoints

Ten endpoints across servers, discovery, trends, forecasts, account usage, and webhook management. Each lists its required scope, minimum plan, and credit cost, with a runnable request and a realistic response.

GET/v1/servers/find

Best live servers for a game.

Returns a ranked list of live, joinable servers for a game, scored by our quality model (low ping, healthy fill, low crash rate, no exploiter flags). Pair with the `region` and `fill` filters to route a player to the server they actually want — a fresh low-fill lobby or a near-full high-energy one.

Scopeservers:readMin planFreeCost1 credit

Parameters

Name	In	Type	Required	Description
game	query	string	required	Game slug or numeric place id, e.g. blade-ball or 189707.
region	query	string	optional	Preferred region: us-east, us-west, eu, asia, oce, sa. Defaults to the caller's inferred region.
fill	query	enum	optional	Target fill level: low, medium, or high. Biases ranking toward emptier or fuller servers.
limit	query	integer	optional	Max results to return, 1–50. Defaults to 10.

Example request

GET /v1/servers/find

curl https://api.riip.gg/v1/servers/find \
  -H "Authorization: Bearer rk_live_7c1f9a..." \
  -G \
  --data-urlencode "game=blade-ball" \
  --data-urlencode "region=eu" \
  --data-urlencode "fill=low" \
  --data-urlencode "limit=3"

Example response

200 OK · application/json

{
  "game": "blade-ball",
  "region": "eu",
  "results": [
    {
      "server_id": "eu-w-9f3a2",
      "players": 3,
      "cap": 8,
      "quality": 91,
      "region": "eu-west",
      "join_url": "https://www.roblox.com/games/start?placeId=189707&serverId=eu-w-9f3a2"
    },
    {
      "server_id": "eu-w-1b7c4",
      "players": 4,
      "cap": 8,
      "quality": 88,
      "region": "eu-west",
      "join_url": "https://www.roblox.com/games/start?placeId=189707&serverId=eu-w-1b7c4"
    },
    {
      "server_id": "eu-c-05de1",
      "players": 2,
      "cap": 8,
      "quality": 84,
      "region": "eu-central",
      "join_url": "https://www.roblox.com/games/start?placeId=189707&serverId=eu-c-05de1"
    }
  ],
  "credits_used": 1
}

Results are ordered best-first. quality is a 0–100 composite; join_url is a deep link the player can open directly.

GET/v1/servers/stats

Occupancy & health for one server.

Returns live occupancy, latency, and a health verdict for a single server previously returned by servers/find. Use it to re-check a server just before you route a player, since fill and health move in seconds.

Scopeservers:readMin planFreeCost1 credit

Parameters

Name	In	Type	Required	Description
server_id	query	string	required	Server id from a prior servers/find result, e.g. eu-w-9f3a2.

Example request

GET /v1/servers/stats

curl https://api.riip.gg/v1/servers/stats \
  -H "Authorization: Bearer rk_live_7c1f9a..." \
  -G \
  --data-urlencode "server_id=eu-w-9f3a2"

Example response

200 OK · application/json

{
  "server_id": "eu-w-9f3a2",
  "game": "blade-ball",
  "region": "eu-west",
  "players": 4,
  "cap": 8,
  "fill_ratio": 0.5,
  "ping_ms": 34,
  "quality": 90,
  "health": "healthy",
  "uptime_seconds": 5821,
  "last_seen": "2026-07-18T22:41:07Z",
  "credits_used": 1
}

health is one of healthy, degraded, or full. A 404 with code not_found means the server has since closed.

GET/v1/discovery/search

Quality-ranked game search.

Full-text game search ranked by our anti-clone quality model rather than raw play counts, so original, well-retained experiences surface above low-effort copies. Cursor-paginated for building browse and autocomplete surfaces.

Scopediscovery:readMin planDevCost1 credit

Parameters

Name	In	Type	Required	Description
q	query	string	required	Search query, e.g. "anime fighting" or a partial title.
genre	query	string	optional	Restrict to a genre, e.g. rpg, simulator, fighting, tycoon, horror.
limit	query	integer	optional	Results per page, 1–50. Defaults to 20.
cursor	query	string	optional	Opaque cursor from a prior response's next_cursor. Omit for the first page.

Example request

GET /v1/discovery/search

curl https://api.riip.gg/v1/discovery/search \
  -H "Authorization: Bearer rk_live_7c1f9a..." \
  -G \
  --data-urlencode "q=anime fighting" \
  --data-urlencode "genre=fighting" \
  --data-urlencode "limit=2"

Example response

200 OK · application/json

{
  "query": "anime fighting",
  "results": [
    {
      "game": "blade-ball",
      "place_id": 189707,
      "title": "Blade Ball",
      "genre": "fighting",
      "quality": 93,
      "ccu": 148203,
      "originality": 0.97,
      "thumbnail_url": "https://cdn.riip.gg/thumbs/blade-ball.webp"
    },
    {
      "game": "anime-fruit-simulator",
      "place_id": 774221,
      "title": "Anime Fruit Simulator",
      "genre": "fighting",
      "quality": 79,
      "ccu": 41022,
      "originality": 0.71,
      "thumbnail_url": "https://cdn.riip.gg/thumbs/anime-fruit-simulator.webp"
    }
  ],
  "next_cursor": "eyJvIjoyMCwicSI6ImFuaW1lIn0",
  "credits_used": 1
}

originality is a 0–1 anti-clone score. When next_cursor is null there are no further pages.

GET/v1/discovery/recommendations

"Games like X" recommendations.

Returns games similar to a seed title using our embedding vectors over gameplay, audience, and retention signals — not just shared tags. Ideal for "more like this" rails and cross-promotion.

Scopediscovery:readMin planDevCost2 credits

Parameters

Name	In	Type	Required	Description
game	query	string	required	Seed game slug or place id to find neighbours for.
limit	query	integer	optional	Number of recommendations, 1–25. Defaults to 10.

Example request

GET /v1/discovery/recommendations

curl https://api.riip.gg/v1/discovery/recommendations \
  -H "Authorization: Bearer rk_live_7c1f9a..." \
  -G \
  --data-urlencode "game=blade-ball" \
  --data-urlencode "limit=3"

Example response

200 OK · application/json

{
  "seed": "blade-ball",
  "results": [
    { "game": "sword-legends", "title": "Sword Legends", "similarity": 0.94, "quality": 87 },
    { "game": "deflect-arena", "title": "Deflect Arena", "similarity": 0.91, "quality": 82 },
    { "game": "parry-masters", "title": "Parry Masters", "similarity": 0.88, "quality": 80 }
  ],
  "model": "riip-embed-2026.06",
  "credits_used": 2
}

similarity is cosine distance in [0,1]; results are ordered most-similar-first.

GET/v1/trends/top-games

Trending & top games by genre.

Ranks games by momentum over a rolling window, blending concurrent players with growth rate so fast-climbing titles surface before they peak. Filter by genre to track a single category.

Scopetrends:readMin planProCost2 credits

Parameters

Name	In	Type	Required	Description
genre	query	string	optional	Restrict to a genre, e.g. simulator. Omit for the overall board.
window	query	enum	optional	Trend window: 24h, 7d, or 30d. Defaults to 24h.
limit	query	integer	optional	Number of games to return, 1–100. Defaults to 25.

Example request

GET /v1/trends/top-games

curl https://api.riip.gg/v1/trends/top-games \
  -H "Authorization: Bearer rk_live_7c1f9a..." \
  -G \
  --data-urlencode "genre=simulator" \
  --data-urlencode "window=7d" \
  --data-urlencode "limit=3"

Example response

200 OK · application/json

{
  "genre": "simulator",
  "window": "7d",
  "results": [
    { "rank": 1, "game": "grow-a-garden", "title": "Grow a Garden", "ccu": 921044, "growth_pct": 18.4, "quality": 90 },
    { "rank": 2, "game": "fisch", "title": "Fisch", "ccu": 512380, "growth_pct": 9.7, "quality": 88 },
    { "rank": 3, "game": "pet-sim-99", "title": "Pet Simulator 99", "ccu": 488512, "growth_pct": -2.1, "quality": 85 }
  ],
  "generated_at": "2026-07-18T22:00:00Z",
  "credits_used": 2
}

growth_pct is the percentage change in CCU across the window; negative values indicate cooling titles.

GET/v1/forecasts/occupancy

Predicted demand by region.

Forecasts expected concurrent players and server demand per region over a horizon, so you can pre-warm capacity, schedule events, or time sponsored placements to a game's regional peaks. Backed by our AI-native occupancy model.

Scopeforecasts:readMin planProCost5 credits

Parameters

Name	In	Type	Required	Description
game	query	string	required	Game slug or place id to forecast.
region	query	string	optional	Restrict the forecast to one region, e.g. us-east. Omit for all regions.
horizon_days	query	integer	optional	Days to forecast forward, 1–14. Defaults to 7. Values above 14 return 422.

Example request

GET /v1/forecasts/occupancy

curl https://api.riip.gg/v1/forecasts/occupancy \
  -H "Authorization: Bearer rk_live_7c1f9a..." \
  -G \
  --data-urlencode "game=blade-ball" \
  --data-urlencode "region=us-east" \
  --data-urlencode "horizon_days=3"

Example response

200 OK · application/json

{
  "game": "blade-ball",
  "region": "us-east",
  "horizon_days": 3,
  "unit": "expected_ccu",
  "points": [
    { "date": "2026-07-19", "peak_ccu": 51200, "peak_hour_utc": 23, "confidence": 0.86 },
    { "date": "2026-07-20", "peak_ccu": 58940, "peak_hour_utc": 22, "confidence": 0.83 },
    { "date": "2026-07-21", "peak_ccu": 44110, "peak_hour_utc": 23, "confidence": 0.79 }
  ],
  "model": "riip-forecast-2026.07",
  "credits_used": 5
}

confidence is the model's 0–1 self-reported certainty; peak_hour_utc is the predicted daily peak in UTC.

GET/v1/account/usage

Current-period metered usage.

Returns the calling key's account usage for the current billing period — calls made, quota, credits consumed, and projected overage. Metering reads are free and do not count against your quota.

Scopeaccount:readMin planFreeCost0 credits

Parameters

No parameters. The key in the Authorization header identifies the account.

Example request

GET /v1/account/usage

curl https://api.riip.gg/v1/account/usage \
  -H "Authorization: Bearer rk_live_7c1f9a..."

Example response

200 OK · application/json

{
  "plan": "dev",
  "period_start": "2026-07-01T00:00:00Z",
  "period_end": "2026-08-01T00:00:00Z",
  "calls_made": 42877,
  "calls_included": 100000,
  "credits_used": 61240,
  "overage_calls": 0,
  "overage_amount_usd": 0.00,
  "rate_limit_per_min": 120
}

credits_used aggregates the per-call credit cost; overage begins once calls_made exceeds calls_included.

POST/v1/webhooks

Register a webhook endpoint.

Registers an HTTPS endpoint to receive signed event deliveries. The response includes a per-endpoint signing secret (shown once) you use to verify the X-RIIP-Signature header on each delivery.

Scopewebhooks:writeMin planDevCost0 credits

Parameters

Name	In	Type	Required	Description
url	body	string	required	HTTPS endpoint to deliver events to. Must be publicly resolvable; private and loopback ranges are rejected.
events	body	string[]	required	Event types to subscribe to, e.g. ["usage.threshold_reached", "billing.payment_failed"].

Example request

POST /v1/webhooks

curl -X POST https://api.riip.gg/v1/webhooks \
  -H "Authorization: Bearer rk_live_7c1f9a..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.yourapp.com/riip",
    "events": ["usage.threshold_reached", "billing.payment_failed"]
  }'

Example response

200 OK · application/json

{
  "id": "wh_3kd91a",
  "url": "https://hooks.yourapp.com/riip",
  "events": ["usage.threshold_reached", "billing.payment_failed"],
  "signing_secret": "whsec_9f2a...shown_once",
  "status": "active",
  "created_at": "2026-07-18T22:45:10Z",
  "credits_used": 0
}

Store signing_secret now — it is never returned again. A url in a private/loopback range returns 422 unprocessable_entity.

GET/v1/webhooks

List registered webhooks.

Returns every webhook endpoint registered on the account, with its subscribed events and recent delivery status. Signing secrets are never included.

Scopewebhooks:readMin planDevCost0 credits

Parameters

No parameters. The key in the Authorization header identifies the account.

Example request

GET /v1/webhooks

curl https://api.riip.gg/v1/webhooks \
  -H "Authorization: Bearer rk_live_7c1f9a..."

Example response

200 OK · application/json

{
  "data": [
    {
      "id": "wh_3kd91a",
      "url": "https://hooks.yourapp.com/riip",
      "events": ["usage.threshold_reached", "billing.payment_failed"],
      "status": "active",
      "last_delivery": {
        "event": "usage.threshold_reached",
        "status": "delivered",
        "response_code": 200,
        "at": "2026-07-18T21:12:44Z"
      },
      "created_at": "2026-07-12T09:03:00Z"
    }
  ],
  "next_cursor": null,
  "credits_used": 0
}

status is active or disabled; endpoints are auto-disabled after repeated delivery failures (see Webhooks).

DELETE/v1/webhooks/{id}

Delete a webhook.

Permanently removes a webhook endpoint. In-flight deliveries already queued may still arrive; no new events will be sent. Responds 204 No Content on success.

Scopewebhooks:writeMin planDevCost0 credits

Parameters

Name	In	Type	Required	Description
id	path	string	required	Webhook id to delete, e.g. wh_3kd91a.

Example request

DELETE /v1/webhooks/{id}

curl -X DELETE https://api.riip.gg/v1/webhooks/wh_3kd91a \
  -H "Authorization: Bearer rk_live_7c1f9a..."

Example response

200 OK · application/json

HTTP/1.1 204 No Content

A successful delete returns an empty body. Deleting an unknown id returns 404 not_found.

Delivery

Webhooks

Register an HTTPS endpoint and RIIP will POST signed JSON events to it as they happen — no polling. Deliveries are signed, retried, and SSRF-guarded. Manage endpoints with the /v1/webhooks endpoints above.

Event types

Event	Fires when
usage.threshold_reached	Metered usage crossed a configured percentage of the monthly quota (e.g. 80%, 100%).
billing.invoice_created	A monthly invoice — base plan plus any overage — was finalized for the account.
billing.payment_failed	A charge for an invoice was declined. Access enters a grace period until it clears.
server.health_changed	A server you subscribed to crossed a health threshold (healthy ↔ degraded ↔ full).

Example delivery

POST · webhook delivery

POST /riip HTTP/1.1
Host: hooks.yourapp.com
Content-Type: application/json
X-RIIP-Signature: t=1752878400,v1=5257a869e7b...c1e9d
X-RIIP-Event: usage.threshold_reached
X-RIIP-Delivery: evt_7f2c91

{
  "id": "evt_7f2c91",
  "type": "usage.threshold_reached",
  "created_at": "2026-07-18T22:00:00Z",
  "account_id": "acct_9a12",
  "data": {
    "threshold_pct": 80,
    "calls_made": 80012,
    "calls_included": 100000,
    "period_end": "2026-08-01T00:00:00Z"
  }
}

Verifying the signature

Each delivery carries an X-RIIP-Signature header of the form t=<timestamp>,v1=<hex>. The signature is an HMAC-SHA256 over timestamp + "." + rawBody, keyed by the per-endpoint signing_secret returned when you registered. Compute the same HMAC over the raw request body (not the re-serialized JSON), compare in constant time, and reject deliveries whose timestamp is more than five minutes old to defeat replays.

verify · node.js

import crypto from "node:crypto";

// Express raw-body handler. Compare in constant time; reject stale timestamps.
function verify(rawBody, header, secret) {
  const [tsPart, sigPart] = header.split(",");
  const timestamp = tsPart.split("=")[1];
  const signature = sigPart.split("=")[1];

  const expected = crypto
    .createHmac("sha256", secret)
    .update(timestamp + "." + rawBody)
    .digest("hex");

  const ok = crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
  return ok && fresh;
}

Retries, DLQ & SSRF

Your endpoint must answer 2xx within 5 seconds. Any non-2xx, timeout, or connection error triggers exponential-backoff retries (roughly 1m, 5m, 30m, 2h, 6h) with jitter over ~24 hours. A delivery that never succeeds lands in a dead-letter queue you can inspect and replay from the dashboard, and an endpoint that keeps failing is auto-disabled and reported via server.health_changed-style status. At registration we validate the target: only public HTTPS hosts are accepted — private, loopback, and link-local ranges are rejected with 422, and each delivery re-resolves DNS to a public address to prevent SSRF via rebinding.

Ready to build?

Mint a scoped key, make your first metered call, and wire up a webhook in minutes.

Get an API key API overview