API Reference

Integrate AI-powered personalized offers into your game with two endpoints.

Base URLhttps://api.qyren.ai

All requests require an X-API-Key header. Get your key from the Qyren Dashboard.

POST/v2/recommend

Get Personalized Offers

Returns a ranked list of the most relevant offers for a player, personalized in real-time based on their session and profile.

Authentication

NameTypeRequiredDescription
X-API-KeystringrequiredYour Qyren API key
Content-Typestringrequiredapplication/json

Request Body

NameTypeRequiredDescription
game_idstringrequiredYour game identifier
player_idstringrequiredUnique player identifier
session_contextobjectrequiredCurrent session metadata (e.g. level, playtime, segment)
inventory_gapsarrayoptionalItems or categories the player is missing
max_resultsintegeroptionalMaximum number of offers to return (default: 5)

Example Request

curl
curl -X POST https://api.qyren.ai/v2/recommend \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "game_id": "ool-mmo",
    "player_id": "player_8a2f",
    "session_context": {
      "level": 34,
      "minutes_played": 18,
      "segment": "mid-spender"
    },
    "inventory_gaps": ["legendary_sword", "health_pack"],
    "max_results": 3
  }'

Response

Returns an array of ranked offers, each with an offer_id, confidence score, and rank position.

json
[
  {
    "offer_id": "summer_blade_bundle",
    "score": 0.91,
    "rank": 1
  },
  {
    "offer_id": "health_pack_10x",
    "score": 0.84,
    "rank": 2
  },
  {
    "offer_id": "gold_starter_500",
    "score": 0.76,
    "rank": 3
  }
]
POST/v1/feedback

Report Outcome

Send the outcome of an offer interaction back to Qyren. This feedback loop is how the AI learns and improves recommendations over time.

Authentication

NameTypeRequiredDescription
X-API-KeystringrequiredYour Qyren API key
Content-Typestringrequiredapplication/json

Request Body

NameTypeRequiredDescription
game_idstringrequiredYour game identifier
player_idstringrequiredUnique player identifier
offer_idstringrequiredThe offer that was shown
outcomeenumrequired"converted", "dismissed", or "expired"
revenue_usdnumberoptionalRevenue amount in USD (required when outcome is converted)

Example Request

curl
curl -X POST https://api.qyren.ai/v1/feedback \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "game_id": "ool-mmo",
    "player_id": "player_8a2f",
    "offer_id": "summer_blade_bundle",
    "outcome": "converted",
    "revenue_usd": 9.99
  }'

Response

Returns a confirmation that the feedback was recorded.

json
{
  "status": "ok"
}

Integration Flow

1

Player enters a monetization surface (shop, offer wall, post-match)

2

Your server calls POST /v2/recommend with player context

3

Qyren returns ranked offers — display them to the player

4

When the player acts (buys, dismisses, or offer expires), call POST /v1/feedback

Need help integrating? We'll walk you through it.

Book an Integration Call