Supported evaluation protocols — REST, gRPC, Connect-RPC, OFREP, SSE
Last updated November 14, 2026
Protocols
Flaggr supports multiple evaluation protocols to fit any architecture. The examples below all evaluate the same flag (checkout-v2 for user-123) so you can compare protocols side by side.
Use Connect-RPC or gRPC on the data plane for latency-sensitive server workloads, REST for portability, OFREP to keep any OpenFeature SDK, and SSE to push changes to clients in real time.
REST API
The standard HTTP/JSON API for flag evaluation. Hosts lists which paths api.flaggr.dev serves from the data plane and which it sends to flaggr.dev.
Evaluate a Flag
curl -s -X POST https://api.flaggr.dev/api/flags/evaluate \
-H "Authorization: Bearer fgr_abc123xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"flagKey": "checkout-v2",
"serviceId": "web-app",
"environment": "production",
"context": {
"targetingKey": "user-123",
"email": "alice@example.com"
},
"defaultValue": false
}' | jqResponse:
{
"flagKey": "checkout-v2",
"value": true,
"reason": "TARGETING_MATCH",
"variant": "enabled"
}Connect-RPC
Type-safe RPC-style protocol with protobuf-shaped JSON values. Flaggr exposes Connect-compatible JSON endpoints under /api/connect/* on flaggr.dev (api.flaggr.dev doesn't serve these paths); the raw gRPC-Web proxy is separate and lives under /api/grpc-web/*. The data plane at api.flaggr.dev serves the flaggr.v1.EvaluationService methods to generated Connect and gRPC-Web clients at the service paths (/flaggr.v1.EvaluationService/ResolveBoolean). Requests may include the Connect-Protocol-Version: 1 header.
Context attributes go in typed maps (stringAttributes, numberAttributes, boolAttributes) next to targetingKey; other context fields are ignored. Without environment, these endpoints evaluate production.
Evaluate a Flag
curl -s -X POST https://flaggr.dev/api/connect/evaluate \
-H "Authorization: Bearer fgr_abc123xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Connect-Protocol-Version: 1" \
-d '{
"flagKey": "checkout-v2",
"serviceId": "web-app",
"environment": "production",
"context": {
"targetingKey": "user-123",
"stringAttributes": { "email": "alice@example.com" }
}
}' | jqResponse:
{
"flagKey": "checkout-v2",
"value": { "boolValue": true },
"variant": "enabled",
"reason": 3,
"metadata": {},
"evaluatedAt": "2025-07-20T10:30:00.000Z",
"flagVersion": 1
}reason is the EvaluationReason enum's number: 1 STATIC, 2 DEFAULT, 3 TARGETING_MATCH, 4 SPLIT, 5 CACHED, 6 FLAG_NOT_FOUND, 7 ERROR, 8 DISABLED. A flag that doesn't exist answers 200 with reason 6 and your defaultValue (or { "boolValue": false }).
The evaluator's own reasons map to the closest value, on /api/connect/* and /api/grpc-web alike: a variant split (VARIANT) and an experiment assignment are 4 (SPLIT), an identity override is 1 (STATIC), and a failed prerequisite or mutual exclusion, which serve the default value, are 2 (DEFAULT). The data plane at api.flaggr.dev maps a variant split and an identity override the same way; it doesn't evaluate prerequisites, mutual exclusion or experiments.
gRPC-Web
Binary gRPC-Web protocol for browser environments. On flaggr.dev, use https://flaggr.dev/api/grpc-web as the base URL; the data plane serves gRPC-Web at its root, https://api.flaggr.dev. Generated Connect-Web clients append service/method paths such as /flaggr.v1.EvaluationService/ResolveBoolean. No generated gRPC-Web client is published; from TypeScript, @flaggr/sdk evaluates over REST and streams over SSE.
On flaggr.dev (/api/grpc-web), request fields are validated: serviceId, flagKey and apiToken (a credential in the body; an Authorization header wins) must be strings and flagKeys a list of flag keys (otherwise 400). environment is an environment name or the proto Environment enum (ENVIRONMENT_PRODUCTION or 3 mean production). Unset (or 0) means development there and production on the data plane (api.flaggr.dev), which reads the key only from the Authorization header. GetConfiguration and StreamFlags return the whole service unless the request names flagKeys. A flag-scoped key must list its flags in flagKeys (a flagKey field doesn't narrow these two calls). StreamFlags forwards only its environment's changes, for the flags it returns, where the caller may read them.
Streaming Updates
FlagStreamService/StreamFlags streams flag changes over gRPC-Web. With @flaggr/sdk 0.5.0 or later, the same changes arrive over SSE. (0.4.0 opens an EventSource with the key in ?token=, which api.flaggr.dev refuses with 401, and it doesn't load as an ES module; see TypeScript SDK.)
On flaggr.dev, streams re-check their access about once a minute, and a stream whose access is gone ends with permission_denied, or unavailable after two failed re-checks in a row (see Real-Time Updates). On api.flaggr.dev, StreamFlags and SyncFlags re-check too: first 30–60 seconds after they open, then every 60 seconds. They end with unauthenticated when the key no longer authenticates (revoked, rotated, or its project deleted), permission_denied when it no longer covers the service, environment or flagKeys the stream named, and unavailable after two failed lookups in a row. On api.flaggr.dev, a key with an expiry ends its stream at that expiry, and a SyncFlags call must send its subscribe message within 30 seconds of opening.
import { createFlaggr } from "@flaggr/sdk";
const client = createFlaggr({
serviceId: "my-service",
apiKey: "fgr_abc123xxxxxxxxxxxx",
updateMode: "stream",
});
const unsubscribe = client.onFlagChange("checkout-v2", ({ newValue }) => {
console.log(`checkout-v2 changed to ${newValue}`);
});OFREP (OpenFeature Remote Evaluation Protocol)
Standard OpenFeature remote evaluation protocol. Any OFREP-compatible client works with Flaggr without code changes.
Evaluate a Flag
curl -s -X POST https://api.flaggr.dev/api/ofrep/v1/evaluate/flags/checkout-v2 \
-H "Authorization: Bearer fgr_abc123xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "X-Service-Id: web-app" \
-H "X-Environment: production" \
-d '{
"context": {
"targetingKey": "user-123",
"email": "alice@example.com"
}
}' | jqResponse follows the OFREP specification:
{
"key": "checkout-v2",
"value": true,
"reason": "TARGETING_MATCH",
"variant": "enabled",
"metadata": {
"evaluatedAt": "2025-07-20T10:30:00Z",
"configVersion": "2025-07-20T10:12:44.000Z",
"flagType": "boolean"
}
}SSE (Server-Sent Events)
Real-time flag change notifications via Server-Sent Events. The connection stays open and pushes events as flags change. The data plane's stream (https://api.flaggr.dev/api/flags/stream) reads the key from the Authorization header only, defaults environment to production, and sends named events:
configuration_syncwhen it connects: every flag of the service and environment ({ type, serviceId, environment, flags, version, timestamp });configuration_deltaafter a change: the changed flags inflagsand the keys of removed flags inremoved;heartbeatevery 30 seconds;access_revoked: sent once before the stream closes, with{ type, reason, message, timestamp }.reasonisaccess_revokedwhen a re-check (30–60 seconds after connect, then every 60 seconds) finds the key revoked, rotated, its project deleted or out of scope, orreauthorization_failedafter two failed lookups in a row.
A key with an expiry ends the stream at that expiry, without an event. The events carry flag configurations, not evaluated values; @flaggr/sdk evaluates them locally. The control plane's streams are described in Real-Time Updates.
# SSE streams stay open — press Ctrl-C to stop
curl -N "https://api.flaggr.dev/api/flags/stream?serviceId=web-app&environment=production" \
-H "Authorization: Bearer fgr_abc123xxxxxxxxxxxx" \
-H "Accept: text/event-stream"Protocol Comparison
| Feature | REST | Connect | gRPC-Web | OFREP | SSE |
|---|---|---|---|---|---|
| Browser support | Yes | Yes | Yes | Yes | Yes |
| Server support | Yes | Yes | No | Yes | Yes |
| Streaming | No | Yes (StreamFlags, server streaming) | Yes | No | Yes |
| Type safety | No | Yes | Yes | No | No |
| Protobuf | No | Yes | Yes | No | No |
| Standard | Custom | Connect | gRPC | OpenFeature | W3C |