Evaluate Endpoint

Evaluate a flag

Evaluates a single flag for the provided user context and returns the resolved variation.

POST /evaluate

Request body

{
  "flagKey": "dark-mode",
  "context": {
    "userId": "user-123",
    "attributes": {
      "plan": "pro",
      "country": "US"
    }
  }
}

Field	Type	Required	Description
`flagKey`	`string`	Yes	The flag to evaluate
`context`	`object`	Yes	User context for targeting
`context.userId`	`string`	No	Unique user identifier (used for percentage rollouts)
`context.attributes`	`object`	No	Custom attributes for targeting rules

Response

{
  "key": "dark-mode",
  "variation": "on",
  "value": true,
  "reason": "fallthrough"
}

Field	Type	Description
`key`	`string`	The flag key that was evaluated
`variation`	`string`	Key of the variation that was served
`value`	`any`	The resolved value (type depends on the flag’s type)
`reason`	`string`	Why this variation was selected (see below)
`prerequisiteKey`	`string`	Present only when `reason` is `prerequisite-failed`: the key of the parent flag that gated this flag off

Evaluation reasons

The reason is returned verbatim from the evaluator and is lower-case:

Reason	Description
`rule-match:<ruleId>`	A targeting rule matched the context. The matched rule’s ID is appended to the reason.
`fallthrough`	Flag is on but no rules matched; the fallthrough variation was served.
`flag-disabled`	Flag is off; the off variation was served.
`prerequisite-failed`	A prerequisite flag did not serve its required variation; the off variation was served. `prerequisiteKey` names the parent flag. See Prerequisite Flags.

A flag key that does not exist returns 404 Not Found rather than a reason value.

Errors

401 Unauthorized — Invalid or missing SDK key.
404 Not Found — The flag key does not exist in this environment.

Evaluation logic

When you call this endpoint, the server runs the following logic:

Flag disabled — If enabled is false, return the offVariation (reason flag-disabled).
Prerequisites — Evaluate each prerequisite’s parent flag against the same context. If any parent does not serve its required variation, return the offVariation (reason prerequisite-failed, with prerequisiteKey set to the first failing parent).
Rules — Evaluate each rule in priority order. If a rule’s conditions match the context, serve according to the rule’s serve config (reason rule-match:<ruleId>).
Fallthrough — If no rules match, serve according to the fallthrough config (reason fallthrough).

For Rollout serve configs, the user is bucketed into a variation based on a hash of the bucketBy attribute (defaulting to userId) and the configured salt.