Evaluation
Evaluation
Client-authenticated flag evaluation and SDK bootstrap endpoints
Overview
The Evaluation resource provides the public endpoints used to resolve feature flags for an environment. It supports evaluating every flag for an evaluation context, fetching the flag definitions and segments required for SDK local evaluation, and evaluating one flag by key.
These routes use a project-scoped API key for the evaluation request. The project is derived from the authenticated key rather than supplied in the URL, so an evaluation request is limited to that key's project. Server keys may also call the evaluation routes.
Note:
Use GET /v1/config when an application will evaluate flags locally after bootstrap. Use POST /v1/evaluate or GET /v1/flags/{flagKey}/eval when the API should resolve values for the supplied context.
Schema
The following fields make up the evaluation request and response shapes. Nested fields are shown with their parent field so the same table covers all three endpoints.
| Field | Type | Required | Description |
|---|---|---|---|
environment | string | Yes | Environment key used for evaluation or configuration bootstrap. |
context | object | Yes for POST /v1/evaluate | Evaluation context containing a subject key and optional attributes. |
context.key | string | Yes | Stable subject identifier, such as a user ID. |
context.attributes | record of attribute values | No | Additional subject attributes used by targeting conditions. |
flagKey | string | Yes in an evaluation result | Flag key associated with an evaluation result. The request supplies this value as the path parameter for single-flag evaluation. |
value | JSON value | Yes in an evaluation result | Resolved flag value. |
variationKey | string | Yes in an evaluation result | Named variation selected for the flag. |
reason | object | Yes in an evaluation result | Resolution metadata. |
reason.kind | OFF, FALLTHROUGH, RULE_MATCH, or ERROR | Yes | Evaluation outcome category. |
reason.ruleId | string | No | Identifier of the targeting rule when one is associated with the result. |
reason.ruleIndex | integer | No | Position of the targeting rule when one is associated with the result. |
reason.error | string | No | Error detail when the evaluation result has an error reason. |
flags | record keyed by flag key, with evaluation results as values | Yes in POST /v1/evaluate response | Resolved values for every flag in the requested environment. |
flags | array of flag definitions | Yes in GET /v1/config response | Definitions the SDK can evaluate locally. Each definition contains key, type, enabled, variations, defaultVariationKey, offVariationKey, and rules. |
flags[].key | string | Yes | Flag identifier. |
flags[].type | boolean, string, number, or json | Yes | Type of the flag's variations. |
flags[].enabled | boolean | Yes | Whether the flag is enabled in the returned definition. |
flags[].variations | array of variation objects | Yes | Named values available for the flag. |
flags[].defaultVariationKey | string | Yes | Default variation key for the environment. |
flags[].offVariationKey | string | Yes | Variation key used when the flag is off. |
flags[].rules | array of targeting rule objects | Yes | Targeting rules defined for the environment. |
segments | array of segment objects | Yes in GET /v1/config response | Reusable segment definitions available to local evaluation. |
segments[].key | string | Yes | Segment identifier. |
segments[].conditions | array of condition objects | Yes | Conditions that define the segment. |
key | string | Yes for GET /v1/flags/{flagKey}/eval | Subject key used when evaluating one flag. |
Endpoints
| Method | Path | Description |
|---|---|---|
POST | /v1/evaluate | Evaluate every flag in an environment for the supplied evaluation context. |
GET | /v1/config | Return every flag definition and segment for an environment so an SDK can bootstrap local evaluation. |
GET | /v1/flags/{flagKey}/eval | Evaluate one flag by key for a subject in an environment. |