REST API Integration

Qyren is a server-to-server REST API. Your game backend calls Qyren; your game client never does. This page walks through the three endpoints you need to wire up: ingest events, request a recommendation, and report feedback.

Base URL and authentication

https://api.qyren.ai

Every request needs a bearer token in the Authorization header:

Authorization: Bearer qyr_live_YOUR_KEY
Content-Type: application/json

Two key prefixes:

qyr_test_… — sandbox. Events validate and store but never affect billing or production models. Recommendations come from a deterministic seed so your tests are repeatable.
qyr_live_… — production. Real events, real recommendations, billable.

Get keys from the dashboard. Never check them into source control. Never ship them in your game client.

Endpoint 1: Ingest events

POST /v1/ingest

Stream every meaningful gameplay, economy, and monetization event to this endpoint. It’s the foundation of everything else — dashboards, alerts, and recommendations are all derived from what you send here.

Request

curl -X POST https://api.qyren.ai/v1/ingest \
  -H "Authorization: Bearer qyr_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event_id": "01HRZX9K0P6M2NCJY8D7T4V3Q1",
        "event_type": "session_start",
        "schema_version": "1.0",
        "game_id": "skylore",
        "player_id": "player_12345",
        "session_id": "sess_01HRZX9K0P",
        "event_time": "2026-04-13T10:00:00Z",
        "device": {"type": "phone", "os": "iOS", "os_version": "17.4"},
        "geo": {"country": "US"}
      }
    ]
  }'

Batching

Up to 100 events per request.
Up to 10 KB per event.
Flush every 2–5 seconds, or whenever you reach ~50 buffered events, whichever comes first. Don’t wait for the batch to fill — latency hurts model quality more than a few extra HTTP calls cost you.

Response codes

Code	Meaning
`202 Accepted`	Every event in the batch was valid and queued.
`207 Multi-Status`	Partial acceptance. Some events accepted, some rejected. Body has `accepted`, `rejected`, and a per-event `errors` array. The accepted ones are stored — only retry the rejected ones after fixing them.
`400 Bad Request`	Whole batch invalid. Malformed JSON, or every event failed validation.
`401 Unauthorized`	Bad or missing API key.
`413 Payload Too Large`	Batch too big or one event too big.
`429 Too Many Requests`	Slow down. Back off and retry.

Partial acceptance example

{
  "accepted": 2,
  "rejected": 1,
  "errors": [
    {
      "event_index": 1,
      "event_id": "01HRZX9K0P6M2NCJY8D7T4V3Q9",
      "field": "properties.revenue_usd",
      "error": "required for purchase events"
    }
  ]
}

event_index is the position in the array you sent. Use it to find the offending event in your local buffer, fix it, and retry just that one. Full schema details are in Event Schema.

Endpoint 2: Request a recommendation

POST /v1/recommend

Call this whenever a player hits a trigger where you’d consider showing an offer — shop opened, level cleared, login bonus, end-of-battle screen.

Request

curl -X POST https://api.qyren.ai/v1/recommend \
  -H "Authorization: Bearer qyr_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "game_id": "skylore",
    "player_id": "player_12345",
    "placement": "shop_main",
    "max_offers": 3,
    "context": {
      "level": 14,
      "currency_balances": {"gold": 12500, "gems": 80},
      "days_since_install": 5
    }
  }'

context is optional but strongly encouraged. The more you tell Qyren about the player’s current state, the better the picks.

Response

{
  "offers": [
    {"offer_id": "starter_bundle_01", "name": "Starter Bundle", "score": 0.74, "rank": 1},
    {"offer_id": "gem_pack_medium",   "name": "Gem Pack (Medium)", "score": 0.61, "rank": 2},
    {"offer_id": "weekly_deal",       "name": "Weekly Deal", "score": 0.52, "rank": 3}
  ],
  "segment": "new_player"
}

Field	Notes
`offers`	Ordered list. Display top-to-bottom in the order returned.
`offers[].offer_id`	The offer to show. Matches the ID you imported via `/v1/offers/import`.
`offers[].name`	Display name from the catalog, included for convenience.
`offers[].rank`	AI-assigned ordering, starting at 1. Lower rank = higher confidence for this player right now.
`offers[].score`	Internal confidence value used for ordering. Useful for diagnostics; don’t surface to players.
`segment`	The behavioral segment Qyren placed this player in for this call (e.g. `new_player`, `whale`).

If no offers are eligible after filtering and pacing, offers is an empty array and you should fall back to your default. When you actually show offers on screen, log an offer_impression event for each one. This is non-negotiable — without impressions, Qyren can’t compute conversion rates and recommendations get worse over time.

Latency and timeouts

p95 under 150ms for /v1/recommend.
Set a client-side timeout of around 500ms.
If the call times out or fails, fall back to a default offer list. Never block gameplay waiting on Qyren.

For triggers in tight loops (end-of-battle popup that fires every 30 seconds), pre-fetch at session start and cache for a few minutes. Re-fetch when the player’s state changes meaningfully (level up, large purchase, currency milestone).

Endpoint 3: Report feedback

POST /v1/feedback

Tell Qyren what happened after a recommendation was shown. This is how the AI engine learns and improves over time.

Request

curl -X POST https://api.qyren.ai/v1/feedback \
  -H "Authorization: Bearer qyr_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "game_id": "skylore",
    "player_id": "player_12345",
    "offer_id": "starter_bundle_01",
    "outcome": "converted",
    "revenue_usd": 4.99,
    "segment": "new_player",
    "days_since_install": 5,
    "session_id": "sess_01HRZX9K0P"
  }'

Field	Required	Notes
`player_id`	yes	The player the offer was shown to.
`offer_id`	yes	The offer they acted on.
`outcome`	yes	One of `converted`, `dismissed`, `expired`, `impression`. See table below.
`game_id`	recommended	Required for per-game learning isolation.
`segment`	recommended	The `segment` returned by `/v1/recommend` for this player.
`revenue_usd`	conditional	Required when `outcome` is `converted`.
`days_since_install`	optional	Used for pacing accounting.
`session_id`	optional	Logged for analytics correlation.

outcome values:

Value	When
`converted`	Player purchased the offer.
`dismissed`	Player closed or ignored the offer.
`expired`	Time-limited offer ended without action.
`impression`	Offer was shown on screen. Equivalent to logging `offer_impression` via `/v1/ingest`; use whichever is easier.

If you’re already sending purchase and offer_impression events on /v1/ingest, Qyren can derive most of this automatically — but explicit feedback closes the loop faster and is recommended for your highest-value placements.

Putting it together

A typical session looks like:

Player opens the game → log session_start to /v1/ingest.
Player opens the shop → call /v1/recommend, get an ordered list, render it, log offer_impression for each rendered offer.
Player taps an offer → log offer_click.
Player completes purchase → log purchase. Optionally also send a converted feedback event.
Player closes the game → log session_end.

That’s the whole loop. Everything else — dashboards, economy health, alerts — falls out of these calls automatically.

Getting Started

Core Concepts

Economy Health

Recommendations

Billing

Integration

API Reference

Glossary

REST API Integration

Base URL and authentication

Endpoint 1: Ingest events

Request

Batching

Response codes

Partial acceptance example

Endpoint 2: Request a recommendation

Request

Response

Latency and timeouts

Endpoint 3: Report feedback

Request

Putting it together

​Base URL and authentication

​Endpoint 1: Ingest events

​Request

​Batching

​Response codes

​Partial acceptance example

​Endpoint 2: Request a recommendation

​Request

​Response

​Latency and timeouts

​Endpoint 3: Report feedback

​Request

​Putting it together

Base URL and authentication

Endpoint 1: Ingest events

Request

Batching

Response codes

Partial acceptance example

Endpoint 2: Request a recommendation

Request

Response

Latency and timeouts

Endpoint 3: Report feedback

Request

Putting it together