DOCS/API Reference/Feature Flags API

Feature Flags API

Evaluate, create, and manage feature flags programmatically via the API.

10 min read

Overview

The Feature Flags API allows you to evaluate flags for players, manage flag configurations, and track experiment results.

Endpoint	Method	Description
`/flags/flags/{key}`	GET	Get flag by key
`/flags/flags/{key}/evaluate`	POST	Evaluate flag
`/flags/flags/evaluate`	POST	Bulk evaluate flags

Evaluate Flag

Evaluate a single flag for a specific player.

POST /v1/flags/flags/{key}/evaluate

bash

curl -X POST class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/flags/flags/new_tutorial/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": class="code-string">"550e8400-e29b-41d4-a716-446655440000",
    class="code-string">"context": {
      class="code-string">"platform": class="code-string">"ios",
      class="code-string">"app_version": class="code-string">"1.2.3"
    }
  }'

Response

Evaluation Response

json

{
  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",
    class="code-string">"evaluation_time_ms": 12
  }
}

Evaluation Reasons

Reason	Description
`default`	No rules matched, using default value
`segment_match`	Player matched a segment rule
`percentage_rollout`	Player included in percentage
`flag_disabled`	Flag is disabled
`player_override`	Player has specific override

Bulk Evaluate Flags

Evaluate multiple flags in a single request.

POST /v1/flags/flags/evaluate

bash

curl -X POST class="code-string">"https:class="code-commentclass="code-string">">//api.ilara.ai/v1/flags/flags/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": class="code-string">"550e8400-e29b-41d4-a716-446655440000",
    class="code-string">"flag_keys": [class="code-string">"new_tutorial", class="code-string">"double_xp", class="code-string">"checkout_variant"],
    class="code-string">"context": {
      class="code-string">"platform": class="code-string">"ios"
    }
  }'

Bulk Evaluation Response

json

{
  class="code-string">"success": true,
  class="code-string">"data": {
    class="code-string">"evaluations": {
      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">"double_xp": {
        class="code-string">"value": false,
        class="code-string">"variant_key": class="code-string">"disabled",
        class="code-string">"reason": class="code-string">"default"
      },
      class="code-string">"checkout_variant": {
        class="code-string">"value": class="code-string">"variant_a",
        class="code-string">"variant_key": class="code-string">"variant_a",
        class="code-string">"reason": class="code-string">"percentage_rollout"
      }
    },
    class="code-string">"evaluation_time_ms": 25
  }
}

Multivariate Flags

Create A/B tests with multiple variants.

Multivariate Flag

json

{
  class="code-string">"key": class="code-string">"checkout_flow",
  class="code-string">"name": class="code-string">"Checkout Flow Experiment",
  class="code-string">"flag_type": class="code-string">"multivariate",
  class="code-string">"variants": [
    {
      class="code-string">"key": class="code-string">"control",
      class="code-string">"value": class="code-string">"original",
      class="code-string">"weight": 34
    },
    {
      class="code-string">"key": class="code-string">"variant_a",
      class="code-string">"value": class="code-string">"simplified",
      class="code-string">"weight": 33
    },
    {
      class="code-string">"key": class="code-string">"variant_b",
      class="code-string">"value": class="code-string">"one_click",
      class="code-string">"weight": 33
    }
  ],
  class="code-string">"enabled": true
}

Experiment Tracking

Track conversions with the variant key to measure experiment results.

Targeting Rules

Complex Targeting

json

{
  class="code-string">"targeting_rules": [
    {
      class="code-string">"name": class="code-string">"Beta Testers",
      class="code-string">"segment_id": class="code-string">"beta-testers",
      class="code-string">"value": true,
      class="code-string">"percentage": 100,
      class="code-string">"priority": 1
    },
    {
      class="code-string">"name": class="code-string">"VIP 50% Rollout",
      class="code-string">"segment_id": class="code-string">"vip-players",
      class="code-string">"value": true,
      class="code-string">"percentage": 50,
      class="code-string">"priority": 2
    },
    {
      class="code-string">"name": class="code-string">"Global 10% Rollout",
      class="code-string">"segment_id": null,
      class="code-string">"value": true,
      class="code-string">"percentage": 10,
      class="code-string">"priority": 3
    }
  ]
}

Error Responses

Status	Code	Description
400	`VALIDATION_ERROR`	Invalid request data
401	`UNAUTHORIZED`	Invalid API key
404	`FLAG_NOT_FOUND`	Flag key does not exist
404	`PLAYER_NOT_FOUND`	Player ID not found

Next Steps

Feature Flags Guide — Best practices
Segments — Create targeting segments
Events API — Track experiment conversions

Players API

Game BFF API