Docs/API Reference/Game BFF API

Game BFF API

Optimized Backend-for-Frontend endpoints designed specifically for game clients — fewer calls, better performance.

12 min read

Overview

The Game BFF (Backend-for-Frontend) API provides optimized composite endpoints specifically designed for game clients. Use these endpoints to reduce network overhead by consolidating multiple API calls into single requests.

When to Use BFF

Use the BFF API for game client integration. It reduces session start from 4+ API calls to just 1 call and provides automatic event batching with intervention delivery.

Endpoint	Method	Description
`/bff/game/init`	POST	Initialize session (player + flags + segments)
`/bff/game/sync`	POST	Sync game state (batch events + interventions)
`/bff/game/end-session`	POST	End session cleanly

Initialize Session

Call this endpoint when starting a game session. It returns the player profile, feature flags, segment memberships, and creates a new session in a single request.

Request

POST /v1/bff/game/init

bash

curl -X POST class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/bff/game/init" \
  -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">"device_info": {
      class="code-string">"platform": class="code-string">"ios",
      class="code-string">"os_version": class="code-string">"17.2",
      class="code-string">"app_version": class="code-string">"2.1.0",
      class="code-string">"device_model": class="code-string">"iPhone 15"
    },
    class="code-string">"requested_flags": [class="code-string">"new_tutorial", class="code-string">"holiday_event", class="code-string">"premium_features"]
  }'

Parameters

Parameter	Type	Required	Description
`player_id`	UUID	Yes	Ilara player ID
`device_info`	object	No	Device metadata for targeting
`requested_flags`	array	No	Specific flags to evaluate (all if omitted)

Response

Success Response

json

{
  class="code-string">"success": true,
  class="code-string">"data": {
    class="code-string">"player": {
      class="code-string">"player_id": class="code-string">"550e8400-e29b-41d4-a716-446655440000",
      class="code-string">"external_id": class="code-string">"user_12345",
      class="code-string">"first_seen": class="code-string">"2024-06-15T10:30:00Z",
      class="code-string">"last_seen": class="code-string">"2025-01-25T14:30:00Z",
      class="code-string">"properties": {
        class="code-string">"level": 42,
        class="code-string">"total_purchases": 5
      }
    },
    class="code-string">"session_id": class="code-string">"sess_abc123xyz",
    class="code-string">"flags": {
      class="code-string">"new_tutorial": { class="code-string">"enabled": true, class="code-string">"variant": class="code-string">"streamlined" },
      class="code-string">"holiday_event": { class="code-string">"enabled": true, class="code-string">"variant": class="code-string">"winter_2025" },
      class="code-string">"premium_features": { class="code-string">"enabled": false }
    },
    class="code-string">"segments": [class="code-string">"high_value", class="code-string">"engaged_players", class="code-string">"ios_users"],
    class="code-string">"server_time": class="code-string">"2025-01-25T14:30:00.123Z"
  }
}

Sync Game State

Use this endpoint during gameplay to send batched events and receive any pending interventions. Call periodically (e.g., every 30-60 seconds) or at key moments.

Request

POST /v1/bff/game/sync

bash

curl -X POST class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/bff/game/sync" \
  -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">"session_id": class="code-string">"sess_abc123xyz",
    class="code-string">"events": [
      {
        class="code-string">"event_name": class="code-string">"level_complete",
        class="code-string">"timestamp": class="code-string">"2025-01-25T14:35:00Z",
        class="code-string">"properties": { class="code-string">"level": 5, class="code-string">"score": 12500, class="code-string">"stars": 3 }
      },
      {
        class="code-string">"event_name": class="code-string">"item_purchase",
        class="code-string">"timestamp": class="code-string">"2025-01-25T14:36:00Z",
        class="code-string">"properties": { class="code-string">"item_id": class="code-string">"sword_01", class="code-string">"currency": class="code-string">"gems", class="code-string">"amount": 50 }
      }
    ],
    class="code-string">"state_updates": {
      class="code-string">"current_level": 6,
      class="code-string">"gems_balance": 150
    }
  }'

Parameters

Parameter	Type	Required	Description
`player_id`	UUID	Yes	Ilara player ID
`session_id`	string	Yes	Session from init response
`events`	array	Yes	Batch of events to track
`state_updates`	object	No	Player state changes

Response

Success Response

json

{
  class="code-string">"success": true,
  class="code-string">"data": {
    class="code-string">"events_accepted": 2,
    class="code-string">"interventions": [
      {
        class="code-string">"intervention_id": class="code-string">"int_xyz789",
        class="code-string">"type": class="code-string">"in_app_message",
        class="code-string">"content": {
          class="code-string">"title": class="code-string">"Great Progress!",
          class="code-string">"body": class="code-string">"You've completed 5 levels today. Keep it up!",
          class="code-string">"cta": class="code-string">"Continue Playing"
        },
        class="code-string">"display_rules": {
          class="code-string">"priority": class="code-string">"high",
          class="code-string">"dismiss_after_seconds": 10
        }
      }
    ],
    class="code-string">"updated_flags": {
      class="code-string">"bonus_rewards": { class="code-string">"enabled": true, class="code-string">"variant": class="code-string">"double_xp" }
    }
  }
}

Event Batching

The sync endpoint accepts up to 50 events per request. Events are processed in order based on their timestamps. Call sync regularly to ensure timely intervention delivery.

End Session

Call this endpoint when the player ends their session (app close, logout, etc.). Include any final events and receive a session summary.

Request

POST /v1/bff/game/end-session

bash

curl -X POST class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/bff/game/end-session" \
  -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">"session_id": class="code-string">"sess_abc123xyz",
    class="code-string">"session_duration_seconds": 1847,
    class="code-string">"final_events": [
      {
        class="code-string">"event_name": class="code-string">"session_end",
        class="code-string">"properties": {
          class="code-string">"levels_played": 5,
          class="code-string">"total_score": 48500,
          class="code-string">"reason": class="code-string">"user_quit"
        }
      }
    ]
  }'

Parameters

Parameter	Type	Required	Description
`player_id`	UUID	Yes	Ilara player ID
`session_id`	string	Yes	Session from init response
`session_duration_seconds`	integer	Yes	Total session duration
`final_events`	array	No	Final events to track

Response

Success Response

json

{
  class="code-string">"success": true,
  class="code-string">"data": {
    class="code-string">"session_summary": {
      class="code-string">"session_id": class="code-string">"sess_abc123xyz",
      class="code-string">"total_events": 47,
      class="code-string">"duration_seconds": 1847,
      class="code-string">"achievements_unlocked": [class="code-string">"first_boss_defeat", class="code-string">"5_level_streak"],
      class="code-string">"interventions_shown": 2,
      class="code-string">"interventions_clicked": 1
    }
  }
}

Standard API vs BFF API

Choose the right API based on your integration type and requirements.

Aspect	Standard API	BFF API
Session start	4+ separate calls	1 consolidated call
Event tracking	Individual or batch	Automatic batching via sync
Interventions	Separate polling required	Delivered in sync response
Flag evaluation	Per-flag endpoint calls	All flags in init response
Best for	Server-side, dashboards	Game clients
Network overhead	Higher	Optimized

Server-Side Integration

For server-to-server integration or dashboard applications, use the standard Events API and Players API instead. The BFF API is optimized specifically for client-side game integration.

Error Responses

Status	Code	Description
400	`VALIDATION_ERROR`	Invalid request parameters
401	`UNAUTHORIZED`	Invalid or missing API key
404	`PLAYER_NOT_FOUND`	Player ID does not exist
404	`SESSION_NOT_FOUND`	Invalid or expired session ID
429	`RATE_LIMIT_EXCEEDED`	Too many requests

Error Response Example

json

{
  class="code-string">"success": false,
  class="code-string">"error": {
    class="code-string">"code": class="code-string">"SESSION_NOT_FOUND",
    class="code-string">"message": class="code-string">"The specified session ID is invalid or has expired",
    class="code-string">"details": {
      class="code-string">"session_id": class="code-string">"sess_abc123xyz",
      class="code-string">"suggestion": class="code-string">"Call /bff/game/init to start a new session"
    }
  }
}

Next Steps

Events API — Standard event tracking for server-side
Players API — Player profile management
Unity SDK — Unity integration with BFF support
Quick Start Guide — Get started with Ilara

Feature Flags API