Feature Flags

Feature flags let you control the rollout of features without deploying new code. Bridge Feature Flags (FF 2.0) uses a three-state model: a flag is off (off for everyone), on (on for everyone), or on-with-rule (on for users matching a rule, with explicit per-branch return values). Rules target users, tenants, devices, or custom attributes, and flags return multi-type values (boolean, string, number, or JSON), not just on/off.

For the conceptual guide, the SDKs, and how to configure flags in Control Center, see the Feature Flags guide. This page documents the REST evaluation API, plus the flag-management endpoints that Control Center and the CLI use.

The evaluation endpoints below are public and require no authentication, so they can be called directly from server-side code or any client without a Bridge SDK.

Evaluation context

Most apps use a framework SDK which evaluates flags locally (an in-memory rule lookup, no network round-trip per eval) and only needs these REST endpoints when you have no SDK, for example server-side evaluation from a language Bridge doesn’t ship an SDK for. When you do call REST, you supply the evaluation context in the request body.

Internally, FF 2.0 evaluates against a { identity, attributes } context. The structured object below is the REST mapping of that model: user.id / tenant.id map to the bucketing identity, and the remaining fields (user.role, tenant.plan, device.key, custom.*, …) become attributes your rules can target. You can send either this structured object or a raw accessToken (JWT), from which Bridge resolves the user/tenant attributes.

{
    "user": { "id": "63d2ab029e23f80afb0daf97", "role": "ADMIN", "name": "John Doe", "email": "john@doe.com", "key": "custom" },
    "tenant": { "id": "63d2ab029e23f80afb0daf90", "plan": "PREMIUM", "name": "My Workspace", "key": "custom" },
    "device": { "key": "iphone" },
    "custom": { "property1": "value1" }
}

All context fields are optional; include only what your flag rules reference.

Paths. The canonical evaluation paths are shown unversioned (/cloud-views/flags/…) and resolve as-is. Other FF 2.0 routes are URI-versioned with a v1 prefix (/v1/…); the unversioned legacy form of those also still resolves. The public API base is https://api.thebridge.dev.

Evaluate a Flag

Evaluate a single feature flag for a given context. This endpoint is public and does not require authentication.

Use GET when you have no targeting context to send, and POST when you do. Both return the same response shape. GET takes no body — it evaluates against the flagctx cookie if one is present on the request, and otherwise against an empty context.

HTTP Request

GET https://api.thebridge.dev/cloud-views/flags/evaluate/APP_ID/FLAG_KEY

POST https://api.thebridge.dev/cloud-views/flags/evaluate/APP_ID/FLAG_KEY

Path Parameters

Parameter	Type	Required	Description
`APP_ID`	`string`	Required	Your application ID
`FLAG_KEY`	`string`	Required	The unique key of the flag to evaluate

Body Parameters (POST)

Parameter	Type	Required	Description
`user`	`object`	Optional	User context: `id`, `role`, `name`, `email`, `key`
`tenant`	`object`	Optional	Tenant context: `id`, `plan`, `name`, `key`
`device`	`object`	Optional	Device context: `key`
`custom`	`object`	Optional	Arbitrary key-value pairs for custom targeting rules
`accessToken`	`string`	Optional	A JWT access token. Can be sent instead of the context object

Response `HTTP 200`

HTTP 200. Returns the evaluation result.

Response Fields

Parameter	Type	Required	Description
`value`	`boolean \| string \| number \| object`	Optional	The typed flag result. The type is inferred from the flag's configured value type. Omitted only on a hard error where the SDK would fall back to your default
`enabled`	`boolean`	Required	Legacy boolean convenience. For a `boolean` flag this is the value itself. For any other value type it reports whether a branch matched — not whether the flag is on. See the note below
`variantIndex`	`number`	Optional	Which rule branch matched: `-1` = the otherwise value, `>= 0` = the zero-based index of the matched branch. A flag in plain `on` state (no rule) reports `0`

Request example — no context (GET):

curl 'https://api.thebridge.dev/cloud-views/flags/evaluate/APP_ID/FLAG_KEY'

Request example — with an evaluation context (POST):

curl --request POST 'https://api.thebridge.dev/cloud-views/flags/evaluate/APP_ID/FLAG_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "user": { "id": "63d2ab029e23f80afb0daf97", "role": "ADMIN" },
  "tenant": { "id": "63d2ab029e23f80afb0daf90", "plan": "PREMIUM" },
  "device": { "key": "iphone" }
}'

Response example (boolean flag):

{
    "enabled": true,
    "value": true,
    "variantIndex": 0
}

Response example (string flag, multi-type value):

{
    "enabled": true,
    "value": "dark",
    "variantIndex": 1
}

A number or json flag returns value typed accordingly (e.g. "value": 50 or "value": { "window": 60, "max": 100 }).

Always read value, not enabled, for non-boolean flags. enabled predates multi-type values and means different things per type. For a boolean flag it is the value. For a string, number, or json flag it reports only whether a rule branch matched — so a flag that is fully on but served its otherwiseValue comes back "enabled": false with a perfectly valid value, and a matched branch returning "" or 0 comes back "enabled": true. It is kept solely so pre-2.0 clients keep working.

▶ POST Try it out

POST https://api.thebridge.dev/cloud-views/flags/evaluate/:APP_ID/:FLAG_KEY

APP_ID URL parameter Your application ID

FLAG_KEY URL parameter The unique key of the flag

Request Body (JSON)

Evaluate Flags in Bulk

Evaluate all flags for a given context in a single request. This endpoint is public and does not require authentication.

HTTP Request

POST https://api.thebridge.dev/cloud-views/flags/bulkEvaluate/APP_ID

Path Parameters

Parameter	Type	Required	Description
`APP_ID`	`string`	Required	Your application ID

Body Parameters

Parameter	Type	Required	Description
`user`	`object`	Optional	User context: `id`, `role`, `name`, `email`, `key`
`tenant`	`object`	Optional	Tenant context: `id`, `plan`, `name`, `key`
`device`	`object`	Optional	Device context: `key`
`custom`	`object`	Optional	Arbitrary key-value pairs for custom targeting rules
`accessToken`	`string`	Optional	A JWT access token. Can be sent instead of the context object

Response `HTTP 200`

HTTP 200 — Returns an object with a flags array. Each entry pairs a flag (the flag key) with its evaluation (the same { enabled, value, variantIndex } shape as a single evaluation). Every flag on the app is returned, including flags whose state is off — those evaluate to their offValue.

Request example

curl --request POST 'https://api.thebridge.dev/cloud-views/flags/bulkEvaluate/APP_ID' \
--header 'Content-Type: application/json' \
--data-raw '{
  "user": { "id": "63d2ab029e23f80afb0daf97", "role": "ADMIN" },
  "tenant": { "id": "63d2ab029e23f80afb0daf90", "plan": "PREMIUM" },
  "device": { "key": "iphone" }
}'

Response example:

{
    "flags": [
        {
            "flag": "iphone-feature",
            "evaluation": {
                "enabled": true,
                "value": true,
                "variantIndex": 0
            }
        },
        {
            "flag": "checkout-cta",
            "evaluation": {
                "enabled": true,
                "value": "Pay now",
                "variantIndex": -1
            }
        }
    ]
}

▶ POST Try it out

POST https://api.thebridge.dev/cloud-views/flags/bulkEvaluate/:APP_ID

APP_ID URL parameter Your application ID

Request Body (JSON)

Managing flags

Feature flags can be managed however fits your workflow: Control Center, the CLI, an AI agent via MCP, or the API directly.

Control Center: build a flag’s rule visually with three states (off / on / on-with-rule), branches, conditions, rollout percentage, and value type.
CLI: bridge flag list/create/update/toggle/delete/schedule/export/import does the same thing from the command line, handy for scripting flag setup or moving flags between environments.
MCP: point an AI coding agent at Bridge’s setup guide (bridge guide <framework>) and it can wire a flag into your code for you as part of shipping a feature.
API: the API behind all three of the above has two parts. Evaluation is what this page documents: evaluate a flag, evaluate in bulk, and the telemetry/live-update traffic the SDKs generate automatically (see SDK telemetry & live updates). Creating and managing flags and their rules is the other part, the same one Control Center and the CLI call, and the endpoints for it are below.

You don’t have to pre-register a flag through any of these first, either. Auto-discovery covers that: the first time your code evaluates an unknown key (via an SDK flag("my-key", default) call or one of the evaluation endpoints above), the key appears in Control Center’s flags list with a “Discovered” badge, ready to configure. See Targeting & Attributes.

Flag-management endpoints

Method	Path	Does
`GET`	`/admin/flags/flags`	List all flags for the app
`POST`	`/admin/flags/flag`	Create a flag
`PUT`	`/admin/flags/flag/:flagId`	Update a flag. A quick on/off toggle is the same call, sending just the new `state`
`DELETE`	`/admin/flags/flag/:flagId`	Delete a flag
`GET`	`/admin/flags/segments`	List reusable rule segments
`POST`	`/admin/flags/segment`	Create a segment
`PUT`	`/admin/flags/segment/:segmentId`	Update a segment
`DELETE`	`/admin/flags/segment/:segmentId`	Delete a segment

Authenticate the same way as the evaluation endpoints (an x-api-key header), but the value is a personal token from bridge auth login, not the app’s static key.

Create and update take the same flag body. All fields are optional; send only what you’re setting:

Field	Type	Does
`key`	`string`	The flag key your code evaluates (e.g. `use_ai`)
`description`	`string`	Shown in Control Center
`state`	`'off' \| 'on' \| 'on-with-rule'`	The three-state model. `on-with-rule` evaluates `rule`
`valueType`	`'boolean' \| 'string' \| 'number' \| 'json'`	What the flag returns (default `boolean`)
`offValue` / `onValue`	matches `valueType`	The values served in the `off` / `on` states
`rule`	`object`	Branches + otherwise + rollout, as built in the Control Center rule builder
`schedule`	`{ at, state } \| null`	A scheduled state transition; `null` clears it

# Create a boolean flag that is on for 20% of users
curl -X POST "https://api.thebridge.dev/admin/flags/flag" \
  -H "x-api-key: $BRIDGE_PERSONAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "new_dashboard",
    "description": "New dashboard rollout",
    "state": "on-with-rule",
    "rule": { "branches": [], "otherwise": { "value": true, "rollout": 20 } }
  }'

Tip: bridge flag --help is the fastest way to see the exact request shape for each endpoint, since the CLI’s options map directly onto these bodies, and bridge flag export shows you a full flag document as JSON.

SDK telemetry & live updates

When you use a framework SDK, it talks to a few additional endpoints on your behalf. You never call these directly; they are listed here only so the traffic is recognizable. All require the app x-api-key header and return HTTP 202:

Endpoint	Purpose
`POST /v1/flags/eval-events`	Batched evaluation telemetry (per-`(identity, flag, value)` counters), flushed on a timer.
`POST /v1/flags/discover`	First-sighting auto-discovery of unknown flag keys, attribute keys, and entitlement keys.
`POST /v1/flags/call-sites`	Call-site fingerprints powering the “where used in code” view.

To receive live rule updates (a flag saved in the dashboard reaches connected apps in ~1 second), the SDK bootstraps a live channel via GET /v1/realtime/config and POST /v1/realtime/authorize, then subscribes over WebSocket. This too is handled entirely by the SDK.

These flows have independent failure budgets: telemetry and discovery never block evaluation, and a dropped live channel freezes flags on their last-known values until reconnect. See the Observability guide for the developer-facing controls.

Feature Flags

Evaluation context

Evaluate a Flag

HTTP Request

Path Parameters

Body Parameters (POST)

Response HTTP 200

Response Fields

Evaluate Flags in Bulk

HTTP Request

Path Parameters

Body Parameters

Response HTTP 200

Managing flags

Flag-management endpoints

SDK telemetry & live updates

Response `HTTP 200`

Response `HTTP 200`