DOCS/SDKs/REST API

REST API

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

20 min read

Base URL

Environment	Base URL
Production	`https://api.ilara.ai/v1`
Development	`http://localhost:18000/v1`

Authentication

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

bash

X-API-Key: pk_live_xxxxxxxxxxxx

Key Type	Prefix	Usage
Public Key	`pk_*`	Client keys - safe for game clients
Secret Key	`sk_*`	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

Method	Endpoint	Description
POST	`/players/players`	Register/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}/session`	Record session
POST	`/players/players/{id}/purchase?amount=4.99`	Record purchase
GET	`/players/players/{id}/lifecycle`	Get player lifecycle
GET	`/players/players/{id}/churn-risk`	Get churn risk

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
  }
}

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

Method	Endpoint	Description
POST	`/events/events`	Track event
POST	`/events/events/batch`	Batch track
GET	`/events/events/stream`	Stream 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

Method	Endpoint	Description
POST	`/flags/flags/{key}/evaluate`	Evaluate flag for player
POST	`/flags/flags/evaluate`	Bulk 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

Method	Endpoint	Description
POST	`/segments/segments/{id}/evaluate`	Evaluate segment membership
GET	`/segments/player/{player_id}`	Get player segments

Rate Limits

Tier	Requests/min	Events/sec
Free	100	10
Growth	1,000	100
Pro	10,000	1,000
Enterprise	Unlimited	Unlimited

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"
  }
}

Code	Description
`VALIDATION_ERROR`	Invalid request data
`NOT_FOUND`	Resource not found
`RATE_LIMIT_EXCEEDED`	Too many requests
`UNAUTHORIZED`	Invalid API key
`INTERNAL_ERROR`	Server error

Client Libraries

Example clients for common languages:

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

Support

Godot

AI Message Generation