---
name: featbit-evaluation-insights-api
description: Expert guidance for using FeatBit's Flag Evaluation REST API and Track Insights REST API to build custom SDKs for platforms without an official FeatBit SDK. Use when user asks about "evaluation API", "flag evaluation endpoint", "evaluate feature flags via HTTP", "track insights", "insight tracking API", "build custom SDK", "Kotlin SDK", "Android SDK", "iOS SDK", "Swift SDK", "Unity SDK", "embedded SDK", "mobile feature flags", "sendToExperiment", or needs to call FeatBit evaluation server directly. Do not use for management API operations (projects, environments, flag CRUD) — use featbit-rest-api for those. Do not use when an official SDK exists for the target language.
license: MIT
metadata:
  author: FeatBit
  version: 1.0.0
  category: api-reference
---

# FeatBit Flag Evaluation & Insights API

Direct HTTP access to FeatBit's evaluation server — the foundation for building custom SDKs on any platform (Kotlin, Swift, Android, iOS, Unity, embedded, etc.).

**Official documentation:**
- Flag Evaluation API: https://docs.featbit.co/api-docs/flag-evaluation-api
  (source: https://github.com/featbit/featbit-docs/blob/main/pages/api-docs/flag-evaluation-api.md)
- Track Insights API: https://docs.featbit.co/api-docs/track-insights-api
  (source: https://github.com/featbit/featbit-docs/blob/main/pages/api-docs/track-insights-api.md)

## When to Use This Skill

Activate when users:
- Build custom FeatBit SDK for Android, iOS/Swift, Kotlin, Unity, or any platform without an official SDK
- Call the evaluation server directly via HTTP without using a client library
- Need to implement flag evaluation + A/B experiment tracking from scratch
- Ask about `sendToExperiment`, variation insights, custom metric events, or batch insight payloads

## Prerequisites

Before writing any code:
1. **Evaluation server URL** — `{evaluation-server-url}` (e.g., `https://eval.your-featbit.com`). Found in your FeatBit dashboard under environment settings.
2. **Environment secret key** — client-side or server-side key. Include in every request header:
   ```
   Authorization: your-environment-secret-key
   ```
   > See [How to get the environment secret](https://docs.featbit.co/sdk/faq#how-to-get-the-environment-secret)

## Core Workflow

This is the recommended pattern for a custom mobile/frontend SDK:

```
Step 1 ─ App launch       →  Evaluate ALL flags (or filtered by tags/keys)
Step 2 ─ Store locally    →  Cache results in memory for fast synchronous reads
Step 3 ─ Track insights   →  Fire-and-forget: send evaluation records to FeatBit
Step 4 ─ Poll for updates →  Repeat Step 1 periodically using `filter.timestamp`
Step 5 ─ Track metrics    →  Send custom events (conversion, click, purchase) as they occur
```

### Step 1: Evaluate Feature Flags

```
POST {evaluation-server-url}/api/public/featureflag/evaluate
Authorization: your-environment-secret-key
Content-Type: application/json
```

Minimal request body:

```json
{
  "user": {
    "keyId": "user-123",
    "name": "John Doe",
    "customizedProperties": [
      { "name": "country", "value": "US" },
      { "name": "plan", "value": "premium" }
    ]
  }
}
```

Response — array of flag evaluation results:

```json
[
  {
    "key": "new-checkout-flow",
    "variation": {
      "id": "08aceef3-5513-4b38-80ad-4b27bebe8871",
      "type": "boolean",
      "value": "true",
      "matchReason": "premium user rule",
      "sendToExperiment": true
    }
  }
]
```

Key fields:
- `variation.value` — always a **string**, cast to the needed type (`"true"` → boolean, `"104857600"` → number)
- `variation.sendToExperiment` — **save this**; pass it unchanged when tracking insights
- `variation.matchReason` — `"flag disabled"` | `"targeted"` | `"{rule name}"` | `"default"`

**Narrow the response with filters** (essential for reducing payload on mobile):

```json
{
  "user": { "keyId": "user-123" },
  "filter": {
    "keys": ["checkout-flow", "theme-color"],
    "tags": ["mobile"],
    "tagFilterMode": "and",
    "timestamp": 1704067200000
  }
}
```

> `filter.timestamp` — Unix ms. Returns only flags modified **after** this timestamp. Pass the timestamp from the previous call to implement efficient polling.

Read `references/flag-evaluation-api.md` for the complete schema, all filter options, and error responses.

### Step 2: Cache Locally

Store the response array in memory keyed by `flag.key`. Serve flag values synchronously from cache — never block UI on a network call.

### Step 3: Track Flag Evaluation Insights (fire-and-forget)

After evaluating flags, send evaluation records asynchronously.

```
POST {evaluation-server-url}/api/public/insight/track
Authorization: your-environment-secret-key
Content-Type: application/json
```

Request body — array of insight objects:

```json
[
  {
    "user": {
      "keyId": "user-123",
      "name": "John Doe",
      "customizedProperties": [
        { "name": "plan", "value": "premium" }
      ]
    },
    "variations": [
      {
        "featureFlagKey": "new-checkout-flow",
        "variation": {
          "id": "08aceef3-5513-4b38-80ad-4b27bebe8871",
          "value": "true"
        },
        "sendToExperiment": true,
        "timestamp": 1704067200000
      }
    ],
    "metrics": []
  }
]
```

> Response: `200 OK` with empty body on success. Do **not** await this in the main UI thread.

**Critical**:
- Copy `variation.id`, `variation.value`, and `sendToExperiment` exactly from the evaluation response. Do **not** derive or guess these values.
- At least one of `variations` or `metrics` must be non-empty in each insight object. A payload where both are empty arrays is a no-op.

### Step 4: Poll for Flag Updates

On a background timer, re-evaluate using `filter.timestamp` set to the time of the last successful poll. Only changed flags are returned — update your cache with the diff.

### Step 5: Track Custom Metric Events

When a user performs a meaningful action (purchase, conversion, click):

```json
[
  {
    "user": { "keyId": "user-123" },
    "variations": [],
    "metrics": [
      {
        "route": "/checkout/complete",
        "type": "CustomEvent",
        "eventName": "purchase-completed",
        "numericValue": 99.99,
        "appType": "Mobile",
        "timestamp": 1704067350000
      }
    ]
  }
]
```

> `appType` — use `"Mobile"` for Android/iOS apps, `"Web"` for browser-based apps.

Read `references/track-insights-api.md` for the complete schema, batch examples, and best practices.

## Decision Map

| Scenario | Action |
|---|---|
| Evaluate all flags on launch | POST evaluate with user, no filter |
| Evaluate only mobile-tagged flags | POST evaluate with `filter.tags: ["mobile"]` |
| Evaluate one specific flag | POST evaluate with `filter.keys: ["flag-key"]` |
| Detect flag changes since last poll | POST evaluate with `filter.timestamp: {lastPollMs}` |
| Record which variation user saw | POST track with `variations` array |
| Record A/B test conversion | POST track with `metrics` array |
| Record both at once | POST track with both `variations` and `metrics` in one payload |

## Mobile SDK Implementation Checklist

Copy and track progress:
- [ ] Step 1: Store evaluation server URL and secret key in app config (never hardcode in source)
- [ ] Step 2: At app startup, call evaluate endpoint and cache results in memory
- [ ] Step 3: Fire-and-forget: post flag variation insights immediately after evaluation
- [ ] Step 4: Implement background polling with `filter.timestamp` to pick up flag changes
- [ ] Step 5: Expose a `getFlag(key, defaultValue)` helper that reads from cache synchronously
- [ ] Step 6: On relevant user action, post metric insights asynchronously
- [ ] Step 7: On user context change (login, upgrade), re-evaluate immediately

## Reference Files

| File | Read when |
|---|---|
| `references/flag-evaluation-api.md` | User asks about exact request/response schema, filter parameters, error codes, or single-flag evaluation |
| `references/track-insights-api.md` | User asks about insights schema, batching multiple users, MetricInsight fields, or best practices |