DOCS/API Reference/Events API

Events API

Complete API reference for tracking and querying events in Ilara.

15 min read

Overview

The Events API allows you to track player actions, query event data, and manage event schemas. Events are the foundation of Ilara analytics.

Endpoint	Method	Description
`/events/events`	POST	Track single event
`/events/events/batch`	POST	Track multiple events
`/events/events/stream`	GET	Stream events (SSE)

Track Event

Request

POST /v1/events/events

bash

curl -X POST class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/events/events" \
  -H class="code-string">"X-API-Key: pk_live_xxx" \
  -H class="code-string">"Content-Type: application/json" \
  -d '{
    class="code-string">"player_id": class="code-string">"550e8400-e29b-41d4-a716-446655440000",
    class="code-string">"event_name": class="code-string">"level_complete",
    class="code-string">"session_id": class="code-string">"session_abc123",
    class="code-string">"timestamp": class="code-string">"2025-01-25T14:30:00Z",
    class="code-string">"properties": {
      class="code-string">"level": 5,
      class="code-string">"score": 12500,
      class="code-string">"time_seconds": 180,
      class="code-string">"stars_earned": 3
    }
  }'

Parameters

Parameter	Type	Required	Description
`player_id`	UUID	Yes	Ilara player ID
`event_name`	string	Yes	Event type identifier
`properties`	object	No	Custom event properties
`session_id`	string	No	Link to session
`timestamp`	ISO 8601	No	Event time (defaults to now)

Response

Success Response

json

{
  class="code-string">"success": true,
  class="code-string">"data": {
    class="code-string">"event_id": class="code-string">"evt_abc123",
    class="code-string">"player_id": class="code-string">"550e8400-e29b-41d4-a716-446655440000",
    class="code-string">"event_name": class="code-string">"level_complete",
    class="code-string">"timestamp": class="code-string">"2025-01-25T14:30:00Z",
    class="code-string">"received_at": class="code-string">"2025-01-25T14:30:00.123Z"
  }
}

Batch Track Events

Track multiple events in a single request for better performance.

POST /v1/events/events/batch

bash

curl -X POST class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/events/events/batch" \
  -H class="code-string">"X-API-Key: pk_live_xxx" \
  -H class="code-string">"Content-Type: application/json" \
  -d '{
    class="code-string">"events": [
      {
        class="code-string">"player_id": class="code-string">"uuid-1",
        class="code-string">"event_name": class="code-string">"item_collect",
        class="code-string">"properties": {class="code-string">"item": class="code-string">"coin", class="code-string">"amount": 100}
      },
      {
        class="code-string">"player_id": class="code-string">"uuid-1",
        class="code-string">"event_name": class="code-string">"enemy_defeat",
        class="code-string">"properties": {class="code-string">"enemy_type": class="code-string">"boss", class="code-string">"damage_dealt": 500}
      },
      {
        class="code-string">"player_id": class="code-string">"uuid-2",
        class="code-string">"event_name": class="code-string">"session_start",
        class="code-string">"properties": {class="code-string">"platform": class="code-string">"ios"}
      }
    ]
  }'

Batch Limits

Maximum 100 events per batch request. Events can be from different players.

Stream Events (SSE)

Subscribe to a real-time Server-Sent Events stream for events as they are ingested.

GET /v1/events/events/stream

bash

curl -N class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/events/events/stream" \
  -H class="code-string">"X-API-Key: pk_live_xxx"

Event Types

Type	Description
`connected`	Initial connection confirmation with game_id
`heartbeat`	Periodic keep-alive with timestamp

Example Stream

SSE Stream Output

text

data: {class="code-string">"type": class="code-string">"connected", class="code-string">"game_id": class="code-string">"your-game-id"}
 
data: {class="code-string">"type": class="code-string">"heartbeat", class="code-string">"timestamp": class="code-string">"2025-01-25T14:30:00+00:00"}

Connection

The stream uses standard SSE protocol. Set Accept: text/event-stream header. The connection will send heartbeats every 30 seconds to keep the connection alive.

Error Responses

Status	Code	Description
400	`VALIDATION_ERROR`	Invalid request parameters
401	`UNAUTHORIZED`	Invalid API key
404	`PLAYER_NOT_FOUND`	Player ID not found
429	`RATE_LIMIT_EXCEEDED`	Too many requests

Next Steps

Players API — Manage player profiles
Events & Properties — Best practices
Custom Reports — Query data

Authentication

Players API