Guides

Server-Side Evaluation

Evaluate feature flags through authenticated API endpoints without local SDK evaluation

Server-Side Evaluation

FlagForge can resolve feature flags on the API when your application does not use the local evaluation path. Send an evaluation context to the API and use the returned value, variation key, and reason in your server code.

The evaluation endpoints are authenticated with a Bearer API key. A project-scoped client key is the normal credential for this surface. A project-scoped server key is also accepted by the API, but a global server key without a project scope cannot be used for evaluation because the project is derived from the key.

Choose an evaluation flow

Flow	Endpoint	Sends a context?	Returns	Use it when
Bootstrap	`GET /v1/config?environment=...`	No	Flag definitions and segments	You want the SDK or another runtime to evaluate locally after one fetch
One flag	`GET /v1/flags/{flagKey}/eval?environment=...&key=...`	Subject key only	One evaluation result	You need one flag for one subject and do not need local definitions
All flags	`POST /v1/evaluate`	Yes, including attributes	A result for every configured flag	You need a consistent snapshot of all flag decisions for a subject

All three routes are under the API base URL and require a project-scoped evaluation credential in Authorization: Bearer <api-key>. The environment value must identify an environment in the project associated with the key.

Note:

Server-side evaluation makes an HTTP request for each evaluation operation. If your application performs many checks, compare this approach with the SDK workflow in SDK Client Guide, which bootstraps definitions and evaluates locally.

Evaluate one flag

Use the single-flag endpoint when the subject key is enough for the flag's targeting rules. The subject key is passed as the key query parameter; this endpoint does not accept an attributes object.

The response includes the flag key, resolved value, selected variation key, and a reason. The reason kind can be OFF, FALLTHROUGH, RULE_MATCH, or ERROR. A missing or unconfigured flag returns an error response rather than an evaluation result.

Evaluate all flags

Use POST /v1/evaluate when decisions depend on attributes or when you need all flag results for one subject. The request body contains the environment and an evaluation context. The context requires a non-empty key and can include an attributes object.

bash

API_URL="http://localhost:4000"
CLIENT_KEY="cli_your_project_client_key"

curl "$API_URL/v1/evaluate" \
  --request POST \
  --header "Authorization: Bearer $CLIENT_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "environment": "production",
    "context": {
      "key": "user-42",
      "attributes": {
        "plan": "pro",
        "country": "US"
      }
    }
  }'

The response places results in a flags object keyed by flag key:

json

{
  "environment": "production",
  "flags": {
    "new-checkout": {
      "flagKey": "new-checkout",
      "value": true,
      "variationKey": "enabled",
      "reason": {
        "kind": "RULE_MATCH",
        "ruleIndex": 0
      }
    }
  }
}

The API evaluates flags using the same targeting, segment, and rollout semantics as the shared evaluation engine. See How Evaluation Works for evaluation order and result reasons.

Bootstrap instead of server-side evaluation

GET /v1/config is not an evaluation request. It returns the definitions for every flag configured in the requested environment plus the project's segments:

bash

API_URL="http://localhost:4000"
CLIENT_KEY="cli_your_project_client_key"

curl "$API_URL/v1/config?environment=production" \
  --header "Authorization: Bearer $CLIENT_KEY"

A bootstrap response has this structure:

json

{
  "environment": "production",
  "flags": [
    {
      "key": "new-checkout",
      "type": "boolean",
      "enabled": true,
      "variations": [
        { "key": "enabled", "value": true },
        { "key": "disabled", "value": false }
      ],
      "defaultVariationKey": "disabled",
      "offVariationKey": "disabled",
      "rules": []
    }
  ],
  "segments": []
}

The TypeScript SDK calls this endpoint during client.init(), then evaluates checks in process. Choose bootstrap when you want synchronous checks after initialization, optional polling, and change listeners. Choose /v1/evaluate or the single-flag endpoint when the API should perform the decision for every request.

Note:

Do not send a global server key or an unscoped credential to the evaluation routes. Use the client key belonging to the project whose environment and flags you are evaluating, and keep server-side credentials out of browser code.

Handle authentication and evaluation errors

Every evaluation request must include an Authorization header in the form Bearer <api-key>. Common failures include:

401 when the header is missing, malformed, or contains an invalid API key.
400 when the environment, context, or query parameters fail validation, or when evaluation cannot determine a project-scoped key.
404 when the environment does not exist or a requested flag is not configured in that environment.

For live request and response schemas, open the API's Swagger UI at /docs or its OpenAPI document at /openapi.json. The API must be running at your configured base URL, such as http://localhost:4000.

Related guides

SDK Client Guide — bootstrap definitions and evaluate locally in a TypeScript application.
How Evaluation Works — understand contexts, targeting, segments, rollouts, and reasons.
Evaluation API reference — find the public evaluation resources and endpoint documentation.

PreviousCore Evaluation Engine NextDatabase Backends