Docs/SDKs/REST API

REST API

Direct REST API reference for integrating Ilara with any platform or custom engine.

20 min read

Base URL

EnvironmentBase URL
Productionhttps://api.ilara.ai/v1
Developmenthttp://localhost:18000/v1

Authentication

All requests require an API key in the X-API-Key header:

bash
X-API-Key: pk_live_xxxxxxxxxxxx
Key TypePrefixUsage
Public Keypk_*Client keys - safe for game clients
Secret Keysk_*Server keys - server-side only, never expose
Keep Secret Keys Safe
Never embed secret keys (sk_*) in game clients or client-side code.

Quick Start

1. Register a Player

cURL
bash
curl -X POST class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/players/players" \
  -H class="code-string">"X-API-Key: pk_live_xxx" \
  -H class="code-string">"Content-Type: application/json" \
  -d '{
    class="code-string">"external_id": class="code-string">"player_123",
    class="code-string">"device_id": class="code-string">"device_abc",
    class="code-string">"attributes": {class="code-string">"level": 5}
  }'

2. Track Events

cURL
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">"uuid-from-step-1",
    class="code-string">"event_name": class="code-string">"purchase",
    class="code-string">"properties": {class="code-string">"item_id": class="code-string">"sword_01", class="code-string">"price": 4.99}
  }'

3. Evaluate Feature Flags

cURL
bash
curl -X POST class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/flags/flags/new-feature/evaluate" \
  -H class="code-string">"X-API-Key: pk_live_xxx" \
  -H class="code-string">"Content-Type: application/json" \
  -d class="code-string">'{"player_id": "uuid-from-step-1"}'

Players API

MethodEndpointDescription
POST/players/playersRegister/update player
GET/players/players/{id}Get player by ID
GET/players/players/external/{external_id}Get player by external ID
PATCH/players/players/{id}Update player attributes
POST/players/players/{id}/sessionRecord session
POST/players/players/{id}/purchase?amount=4.99Record purchase
GET/players/players/{id}/lifecycleGet player lifecycle
GET/players/players/{id}/churn-riskGet churn risk
Register Player Request
json
POST /v1/players/players
{
  class="code-string">"external_id": class="code-string">"player_123",
  class="code-string">"device_id": class="code-string">"device_abc",
  class="code-string">"email": class="code-string">"[email protected]",
  class="code-string">"attributes": {
    class="code-string">"level": 45,
    class="code-string">"country": class="code-string">"US",
    class="code-string">"is_vip": true
  }
}
Register Player Response
json
{
  class="code-string">"success": true,
  class="code-string">"data": {
    class="code-string">"id": class="code-string">"550e8400-e29b-41d4-a716-446655440000",
    class="code-string">"external_id": class="code-string">"player_123",
    class="code-string">"device_id": class="code-string">"device_abc",
    class="code-string">"email": class="code-string">"[email protected]",
    class="code-string">"lifecycle_stage": class="code-string">"active",
    class="code-string">"session_count": 12,
    class="code-string">"total_revenue": 49.99,
    class="code-string">"is_payer": true,
    class="code-string">"first_seen_at": class="code-string">"2025-01-01T00:00:00Z",
    class="code-string">"last_seen_at": class="code-string">"2025-01-25T14:30:00Z",
    class="code-string">"attributes": {
      class="code-string">"level": 45,
      class="code-string">"country": class="code-string">"US",
      class="code-string">"is_vip": true
    }
  }
}

Events API

MethodEndpointDescription
POST/events/eventsTrack event
POST/events/events/batchBatch track
GET/events/events/streamStream events (SSE)
Track Event Request
json
POST /v1/events/events
{
  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">"properties": {
    class="code-string">"level": 5,
    class="code-string">"score": 12500,
    class="code-string">"time_seconds": 180,
    class="code-string">"stars_earned": 3
  }
}
Batch Track Request
json
POST /v1/events/events/batch
{
  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"}
    }
  ]
}

Feature Flags API

MethodEndpointDescription
POST/flags/flags/{key}/evaluateEvaluate flag for player
POST/flags/flags/evaluateBulk evaluate all flags
Evaluate Flag Response
json
POST /v1/flags/flags/new_tutorial/evaluate
{
  class="code-string">"player_id": class="code-string">"550e8400-e29b-41d4-a716-446655440000"
}
 
class=class="code-string">"code-comment">// Response
{
  class="code-string">"success": true,
  class="code-string">"data": {
    class="code-string">"flag_key": class="code-string">"new_tutorial",
    class="code-string">"value": true,
    class="code-string">"variant_key": class="code-string">"enabled",
    class="code-string">"reason": class="code-string">"segment_match",
    class="code-string">"segment_id": class="code-string">"beta-testers"
  }
}

Segments API

MethodEndpointDescription
POST/segments/segments/{id}/evaluateEvaluate segment membership
GET/segments/player/{player_id}Get player segments

Rate Limits

TierRequests/minEvents/sec
Free10010
Growth1,000100
Pro10,0001,000
EnterpriseUnlimitedUnlimited

Error Responses

Error Response Format
json
{
  class="code-string">"success": false,
  class="code-string">"error": {
    class="code-string">"code": class="code-string">"VALIDATION_ERROR",
    class="code-string">"message": class="code-string">"Invalid player_id format"
  }
}
CodeDescription
VALIDATION_ERRORInvalid request data
NOT_FOUNDResource not found
RATE_LIMIT_EXCEEDEDToo many requests
UNAUTHORIZEDInvalid API key
INTERNAL_ERRORServer error

Client Libraries

Example clients for common languages:

  • Python — requests-based client
  • Node.js — fetch-based client
  • Go — net/http client

Support

Previous
Godot
Next
AI Message Generation