Provider API/Game recommendations

Game recommendations

API · Operator → Boss Hub

GET/v1/lobby/recommendations

Recommends games for your lobby: a general popular list, a list for one player, and games similar to a game. Returned games go through the same gate as launch: games that are closed on this site, retired, or lack the requested currency or limits are left out. Country restrictions and the currency list of your wallet settings are not applied here; launch can still answer COUNTRY_BLOCKED or CURRENCY_NOT_SUPPORTED. Requires the games.read scope.

Headers

Header	Description
X-Operator-Id	Your operator ID
X-Timestamp	Unix seconds. Rejected outside ±30 s
X-Signature	hex(HMAC_SHA256(secret, ts + "." + METHOD + "." + path?query + "." + body))
X-Api-Key	Optional. Selects the right secret when you have several keys

Query parameters

typestringrequired

Recommendation type: popular, player, similar.

site_idstring

Site code, e.g. site_mrd01, at most 64 characters. Recommendations are filtered by the rules of this site. Required with an operator-wide key and several sites.

player_idstring

Required for type=player, at most 100 characters. The player ID you send in launch; the player must have been launched on this site at least once.

game_idstring

Required for type=similar, at most 120 characters. Game code, e.g. sultans-ember.

currencyISO 4217

Only games that support this currency and have limits in it. Defaults to the player’s currency (player), otherwise the site default.

platformstring

desktop or mobile. Popularity is counted only from sessions on this device class.

limitinteger

Number of games returned: 1-100, default 20.

Types

type	source	How games are chosen
popular	operator, network	Unique players and rounds per game in the last 30 days. With an operator-wide key, all your sites are counted and site_id only filters; with a site-bound key only that site is counted. If your operator had fewer than 50 unique players in 30 days, network data is used: production, all operators, totals only. A short list is completed from network data.
player	player	The player’s recent and frequent games of the last 90 days, then games similar to them; remaining slots are filled with popular games. Games with 30% or more of the player’s rounds come last. Without history the popular list is returned and source says so.
similar	similarity	Similarity (Jaccard) from unique players who played both games in the last 90 days. Computed daily from production, at least 3 shared players; the 20 most similar games are kept per game, so at most 20 games come back even with a larger limit. The list is empty for a game whose similarity is not computed yet.

Eligibility: Recommendations apply the same rules as GET /v1/games: access, site and market rules, closed games. When a rule changes, old results are not returned; results are cached for at most 2 minutes.

Site key: A site key works on its own site only; popularity is then counted from that site’s data only.

GET /v1/lobby/recommendations?type=player&site_id=site_mrd01&player_id=u_88213&limit=3 HTTP/1.1
Host: staging.example.com
X-Operator-Id: op_meridyen
X-Timestamp: 1762344000
X-Signature: 5b1e7d…c09a

200Recommendations for a player

{
  "recommendation_id": "rec_player_20261105_8d41c0a29f3b_2c7e91d04a6b5f38e1d2c3b4",
  "source": "player",
  "games": [
    {
      "game_id": "jade-vault",
      "name": "Jade Vault",
      "provider": "boss-originals",
      "score": 0.5389,
      "reason": "played"
    },
    {
      "game_id": "neon-koi",
      "name": "Neon Koi",
      "provider": "boss-originals",
      "score": 0.2106,
      "reason": "similar_to_played"
    },
    {
      "game_id": "shining-crown",
      "name": "Shining Crown",
      "provider": "egt",
      "score": 0.8333,
      "reason": "played_most"
    }
  ]
}

422type=player without player_id

{
  "code": "VALIDATION_ERROR",
  "message": "The submitted data is invalid.",
  "request_id": "req_01HF3Q2N",
  "details": { "field": "player_id" }
}

Response fields

Field	Type	Description
recommendation_id	string	Signed recommendation ID. Send it in the launch request when the player clicks. It does not expire; the same query returns the same ID on the same day.
source	string	Source of the list: operator, network, player, similarity.
games	object[]	Recommendations, in display order. Fields below.

games[] fields

Field	Type	Description
game_id	string	Game code. Sent as game_id in launch.
name	string	The game’s name.
provider	string	Provider code.
score	number	0 to 1, four decimals. Its meaning depends on reason, see below.
reason	string	Why the game is on the list.

reason and score

reason	Meaning	score
popular	Popular with your operator	0.5 × unique players / most players + 0.5 × rounds / most rounds
popular_network	Popular across the network	The same formula on network data
played	Played by the player in the last 90 days	0.5 × recency (1 to 0 over 90 days) + 0.5 × rounds / rounds of the player’s most played game
similar_to_played	Similar to the player’s games	Sum of similarities weighted by the player’s share of rounds in each game
played_most	30% or more of the player’s rounds are in this game	Share of rounds
similar	Similar to game_id	Jaccard: unique players of both / unique players of either

Measuring clicks

When the player opens a recommended game, send the recommendation_id value in the POST /v1/game/launch body. Boss Hub writes it to the game session. An ID whose signature does not match, or another operator’s ID, gets 422 VALIDATION_ERROR.

Error codes

Code	HTTP	Meaning
INVALID_SIGNATURE	401	Signature could not be verified
TIMESTAMP_SKEW	401	X-Timestamp is outside ±30 s
IP_NOT_ALLOWED	403	IP is not on the allowlist
SCOPE_MISSING	403	The games.read scope is missing
SCOPE_DENIED	403	site_id is not yours or is outside your key’s scope
NOT_FOUND	404	player: no such player on this site; similar: no such game or no access to it
SITE_REQUIRED	422	Operator-wide key and several sites: send site_id
VALIDATION_ERROR	422	Invalid parameter; player_id or game_id missing
CURRENCY_NOT_SUPPORTED	422	The site does not support this currency
RATE_LIMITED	429	Rate limit exceeded

← PreviousGame list Next →Game launch