Events API

Send us what’s happening in your game. Everything else in Qyren is derived from these events.

Endpoint

POST https://api.qyren.ai/v1/ingest
Authorization: Bearer qyr_live_<your-key>
Content-Type: application/json

Request body

{
  "events": [ Event, Event, ... ]
}

Up to 100 events per batch.
Up to 10 KB per event.
Batches above either limit are rejected.

The event envelope

Every event, regardless of type, has this shape:

Field	Type	Required	Notes
`event_id`	string (ULID)	yes	26 Crockford Base32 chars, optionally with an `evt_` prefix. Generate one per event.
`event_type`	string	yes	One of the allowed types below.
`schema_version`	string	yes	Send `"1.0"`.
`game_id`	string	yes	Your game’s ID. Max 64 chars.
`player_id`	string	yes	1–64 chars, `[a-zA-Z0-9_-]` only.
`session_id`	string	no	Groups events from one play session.
`event_time`	RFC 3339 timestamp	yes	UTC. Must be within ±7 days of the server clock.
`device`	object	no	See below.
`geo`	object	no	See below.
`properties`	object	type-dependent	Event-specific fields.

`device` (optional)

Field	Type	Notes
`type`	string	One of: `phone`, `tablet`, `desktop`, `console`, `other`.
`os`	string	Free-form (e.g. `iOS`, `Android`, `Windows`).
`os_version`	string	Free-form.
`app_version`	string	Your game’s build version.
`sdk_version`	string	If you wrap our API in an internal SDK.

`geo` (optional)

Field	Type	Notes
`country`	string	ISO 3166-1 alpha-2, uppercase (e.g. `US`, `DE`, `JP`).
`region`	string	State/province, free-form.
`timezone`	string	IANA tz name (e.g. `America/Los_Angeles`).

Allowed event types

Session

`event_type`	When to send
`session_start`	Player opens the game.
`session_end`	Player closes or backgrounds for >5 min.
`session_heartbeat`	Optional, every 60s of active play. Useful for long sessions.

Monetization

`event_type`	When to send	Required `properties`
`offer_impression`	Offer displayed on screen.	`offer_id`, `placement`, `position`
`offer_click`	Player taps the offer.	`offer_id`, `placement`
`purchase`	IAP completed successfully.	`offer_id`, `transaction_id`, `store`, `revenue_usd`, `is_first_purchase`
`purchase_failed`	IAP attempted and failed.	`offer_id`, `reason`
`sequence_started`	Player entered an offer sequence.	`sequence_id`
`sequence_step_completed`	Player advanced one step.	`sequence_id`, `step_index`
`sequence_ended`	Sequence completed or abandoned.	`sequence_id`, `outcome`
`ad_impression`	Rewarded/interstitial ad shown.	`ad_network`, `placement`

Progression

`event_type`	When to send
`level_start`	Player starts a level/stage/battle.
`level_complete`	Level finished successfully.
`level_fail`	Level failed.
`milestone_reached`	Any notable achievement (tutorial done, first boss, etc.).

Economy

`event_type`	When to send	Required `properties`
`currency_earned`	Currency enters a balance.	`currency_type`, `amount`, `balance_after`, `source`
`currency_spent`	Currency leaves a balance.	`currency_type`, `amount`, `balance_after`, `sink`
`item_acquired`	Non-currency item obtained.	`item_id`, `quantity`
`item_consumed`	Non-currency item used.	`item_id`, `quantity`

Engagement

`event_type`	When to send
`feature_used`	Player uses a notable feature (guild chat, leaderboard, etc.).
`social_action`	Friend invite, gift sent, guild action.
`achievement_unlocked`	Named achievement earned.
`tutorial_step`	Tutorial step entered/completed.

System

`event_type`	When to send
`recommendation_served`	You showed a Qyren recommendation. (Usually equivalent to `offer_impression`.)
`model_feedback`	Optional — explicit conversion signal back to the recommendation engine.
`offer_suppressed`	You had a recommendation but chose not to show it.
`error`	Client error you want us to correlate with other signals.

Custom

`event_type`	Notes
`custom`	For anything not above. `properties.custom_properties` is a nested map with up to 20 keys.

Property notes

revenue_usd must be a non-negative number.
is_first_purchase is a boolean.
source (for currency_earned) and sink (for currency_spent) are free-form strings. Be consistent — quest_reward everywhere, not sometimes quest_complete.
placement is free-form — whatever names you use internally.
position (in offer_impression) is a 0-indexed integer for where the offer appeared in a list.

Example: a single purchase event

{
  "events": [{
    "event_id": "01HRZX9K0P6M2NCJY8D7T4V3Q1",
    "event_type": "purchase",
    "schema_version": "1.0",
    "game_id": "origins_of_lume",
    "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"},
    "properties": {
      "offer_id": "starter_bundle_01",
      "transaction_id": "apple_txn_1000000123456789",
      "store": "app_store",
      "revenue_usd": 4.99,
      "is_first_purchase": true
    }
  }]
}

Example: a currency flow

{
  "events": [
    {
      "event_id": "01HRZX9K0P6M2NCJY8D7T4V3Q2",
      "event_type": "currency_earned",
      "schema_version": "1.0",
      "game_id": "origins_of_lume",
      "player_id": "player_12345",
      "event_time": "2026-04-13T10:03:00Z",
      "properties": {
        "currency_type": "gold",
        "amount": 500,
        "balance_after": 12500,
        "source": "dungeon_reward"
      }
    },
    {
      "event_id": "01HRZX9K0P6M2NCJY8D7T4V3Q3",
      "event_type": "currency_spent",
      "schema_version": "1.0",
      "game_id": "origins_of_lume",
      "player_id": "player_12345",
      "event_time": "2026-04-13T10:04:00Z",
      "properties": {
        "currency_type": "gold",
        "amount": 2000,
        "balance_after": 10500,
        "sink": "weapon_shop"
      }
    }
  ]
}

Response codes

Code	Meaning
`202 Accepted`	All events valid and queued. Body: `{"accepted": N}`.
`207 Multi-Status`	Batch was partially valid. Body has `accepted`, `rejected`, and a per-event `errors` array.
`400 Bad Request`	Whole batch invalid (malformed JSON, all events failed validation). Body has an `error`, `message`, and `details`.
`401 Unauthorized`	Missing or bad API key.
`413 Payload Too Large`	Batch >100 events or an event >10 KB.
`429 Too Many Requests`	Rate-limited. Back off and retry.

Partial failure example (207)

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

The accepted events are stored; rejected ones are not. It’s safe to retry only the rejected ones after fixing them.

Validation rules in one place

event_id: valid ULID (optional evt_ or similar prefix before the ULID).
event_type: one of the allowed values above.
schema_version: non-empty string. Use "1.0".
game_id: 1–64 chars.
player_id: 1–64 chars, [a-zA-Z0-9_-] only.
event_time: within 7 days of server clock, past or future.
device.type: one of the allowed device types, if present.
geo.country: ISO 3166-1 alpha-2 uppercase, if present.
revenue_usd: non-negative number, if present.
custom events: properties.custom_properties max 20 fields.
Per-type required properties as listed in the tables above.

Best practices

Generate ULIDs server-side. They’re sortable and guaranteed unique across your fleet.
Batch aggressively but not slowly. Flush every 2–5 seconds or at 50 events, whichever comes first.
Retry on 429 and 5xx with exponential backoff starting at 1 second.
Never send PII. No emails, no real names. player_id should be opaque.
Log locally on failure. If we’re down or slow, queue events on disk and retry later. Events up to 7 days old are still accepted.

Getting Started

Core Concepts

Economy Health

Recommendations

Billing

Integration

API Reference

Glossary

Endpoint

Request body

The event envelope

`device` (optional)

`geo` (optional)

Allowed event types

Session

Monetization

Progression

Economy

Engagement

System

Custom

Property notes

Example: a single purchase event

Example: a currency flow

Response codes

Partial failure example (207)

Validation rules in one place

Best practices

​Endpoint

​Request body

​The event envelope

​device (optional)

​geo (optional)

​Allowed event types

​Session

​Monetization

​Progression

​Economy

​Engagement

​System

​Custom

​Property notes

​Example: a single purchase event

​Example: a currency flow

​Response codes

​Partial failure example (207)

​Validation rules in one place

​Best practices

Endpoint

Request body

The event envelope

`device` (optional)

`geo` (optional)

Allowed event types

Session

Monetization

Progression

Economy

Engagement

System

Custom

Property notes

Example: a single purchase event

Example: a currency flow

Response codes

Partial failure example (207)

Validation rules in one place

Best practices