OpenFeature Remote Evaluation Protocol (OFREP) v1 compliance — endpoints, request/response format, and interoperability
Last updated November 21, 2026
OFREP Protocol
Flaggr implements the OpenFeature Remote Evaluation Protocol (OFREP) v1, enabling interoperability with any OFREP-compatible client or provider.
What is OFREP?
OFREP is the standard protocol defined by the OpenFeature project for remote flag evaluation. It provides a vendor-neutral API that any feature flag provider can implement, and any OpenFeature SDK can consume.
OFREP means you can switch between flag providers without changing your application code. Any OFREP-compatible SDK works with Flaggr.
Endpoints
Single Flag Evaluation
/api/ofrep/v1/evaluate/flags/{key}Bearer tokenEvaluate a single flag by key.
Headers:
| Header | Required | Description |
|---|---|---|
X-Service-Id | Yes | Service identifier (or the serviceId query param; X-Flaggr-Service-Id is accepted as a legacy name) |
X-Environment | No | development, staging, production (or the environment query param; default: development) |
Authorization | Yes | Bearer API token; requests without one get 401 |
Request:
{
"context": {
"targetingKey": "user-123",
"email": "alice@example.com",
"plan": "enterprise"
}
}Response (200):
{
"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"
}
}metadata.configVersion is when the flag was last changed. The context may hold at most 128 attributes and 64 KiB: beyond that, api.flaggr.dev answers 413 and flaggr.dev answers 400, both with INVALID_CONTEXT. On api.flaggr.dev the request body may be at most 128 KiB. A larger body is answered at the edge, before credentials are checked: 413 { "errorCode": "PARSE_ERROR", "errorDetails": "Request body exceeds limits", "key": "<flag>" }.
On flaggr.dev, credentials are checked before the service is looked up, so an unknown service and one your credential can't read both get 403 PROVIDER_NOT_READY. Rate limits work as for bulk evaluation.
Multi-Language Examples
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",
"plan": "enterprise"
}
}' | jqBulk Evaluation
/api/ofrep/v1/evaluate/flagsBearer token (required)Evaluate multiple flags in a single request.
Takes the same X-Service-Id and X-Environment headers (or serviceId and environment query params) as single-flag evaluation; X-Flaggr-Service-Id and X-Flaggr-Environment are accepted as legacy names. On api.flaggr.dev, the control plane answers bulk evaluation (the data plane serves single flags only).
- Limits (the same as the data plane's): at most 100 keys in
flags, keys of at most 256 characters, and acontextof at most 128 attributes and 64 KiB. Onapi.flaggr.dev, a body over 128 KiB gets413PARSE_ERRORand more than 100 flags400INVALID_CONTEXT. - Credentials: without a Bearer token the answer is
401. A service that doesn't exist and one your credential can't read both get403PROVIDER_NOT_READY. - Rate limits: a request without a token counts against the caller's IP (1,000/min; an IPv6 address counts by its /64). A request with a token counts against that token's allowance (5,000/min) once the token is accepted. A request whose token is refused, or that gets
400before its token is checked, also counts against the IP. Once an address has spent its IP allowance, every request from it gets429until the window resets, whatever token it sends, before the token is checked.429responses carryRetry-After, which browsers can read cross-origin. Throughapi.flaggr.dev, the edge passes your IP on, so these limits count your address, not the edge's.
Request:
{
"context": {
"targetingKey": "user-123",
"plan": "enterprise"
},
"flags": ["checkout-v2", "dark-mode", "new-pricing"]
}Omit flags to evaluate all flags for the service.
Response (200):
{
"flags": [
{
"key": "checkout-v2",
"value": true,
"reason": "TARGETING_MATCH",
"variant": "enabled",
"metadata": { "evaluatedAt": "2025-07-20T10:30:00.000Z", "configVersion": "2025-07-20T10:12:44.000Z" }
},
{
"key": "dark-mode",
"value": false,
"reason": "DEFAULT",
"metadata": { "evaluatedAt": "2025-07-20T10:30:00.000Z", "configVersion": "2025-07-18T08:00:00.000Z" }
},
{
"key": "new-pricing",
"value": "tier-b",
"reason": "SPLIT",
"variant": "tier-b",
"metadata": { "evaluatedAt": "2025-07-20T10:30:00.000Z", "configVersion": "2025-07-19T16:20:00.000Z" }
}
]
}A requested key that doesn't exist comes back in the list with "value": false, "reason": "ERROR" and "errorCode": "FLAG_NOT_FOUND".
Multi-Language Examples
curl -s -X POST https://api.flaggr.dev/api/ofrep/v1/evaluate/flags \
-H "Authorization: Bearer fgr_abc123xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "X-Service-Id: web-app" \
-d '{
"context": {
"targetingKey": "user-123",
"plan": "enterprise"
},
"flags": ["checkout-v2", "dark-mode", "new-pricing"]
}' | jq '.flags[] | "\(.key): \(.value) (\(.reason))"'Server Metadata
/api/ofrep/v1/metadataReturns server capabilities and version information.
Public (no credential), and cached for 5 minutes (Cache-Control: public, max-age=300). It works on https://api.flaggr.dev/api/ofrep/v1/metadata as well as on flaggr.dev.
Response:
{
"name": "Flaggr",
"version": "0.5.0",
"capabilities": {
"cacheInvalidation": true,
"flagChangeEvents": false,
"contextTransform": true
},
"metadata": {
"environment": "production",
"region": "syd1",
"ofrepVersion": "1.0",
"providerType": "remote",
"supportedTypes": "boolean,string,number,object",
"docsUrl": "https://flaggr.dev/docs"
}
}version is the Flaggr release.
OFREP Reasons
| Reason | Description |
|---|---|
STATIC | Statically configured value |
DEFAULT | Default value returned |
TARGETING_MATCH | Targeting rule matched |
SPLIT | Variant percentage split, or a running experiment's assignment |
CACHED | Cached evaluation result |
DISABLED | Flag is disabled |
ERROR | Evaluation error |
UNKNOWN | Any other reason: an identity override, a failed prerequisite or mutual exclusion |
Error Responses
OFREP defines standard error codes:
{
"key": "nonexistent-flag",
"errorCode": "FLAG_NOT_FOUND",
"errorDetails": "Flag not found"
}| Error Code | HTTP Status | When |
|---|---|---|
PARSE_ERROR | 400 | Invalid JSON, or a missing or invalid flag key |
PARSE_ERROR | 413 | On api.flaggr.dev: a request body over 128 KiB, answered at the edge before credentials are checked |
INVALID_CONTEXT | 400 | Missing or invalid service ID or environment, an invalid context, or (bulk) more than 100 flags. On flaggr.dev, also a single-flag context over 128 attributes or 64 KiB |
INVALID_CONTEXT | 413 | Single flag on api.flaggr.dev: a context over 128 attributes or 64 KiB |
PROVIDER_NOT_READY | 401 | No credential. Single-flag requests on api.flaggr.dev also get it for a key that doesn't authenticate or couldn't be checked (see Credential errors) |
PROVIDER_NOT_READY | 403 | A key that doesn't cover the request, or a service your credential can't read or that doesn't exist (the same answer for all). Also a personal access token, and on flaggr.dev (and for bulk on api.flaggr.dev) an unknown, revoked or expired key |
FLAG_NOT_FOUND | 404 | Single flag: the key doesn't exist (bulk lists it with errorCode instead) |
PROVIDER_NOT_READY | 503, 504 | Single flag on api.flaggr.dev: the flag configuration couldn't be loaded in time; retry after Retry-After (flaggr.dev answers 500 GENERAL) |
| — | 429 | Rate limited (both routes on flaggr.dev, bulk on api.flaggr.dev): { "error": "Too Many Requests", "message": "…", "retryAfter": 45 }; retry after Retry-After. Refused credentials count against the caller's IP, and an address that has spent its IP allowance gets 429 whatever token it sends |
GENERAL | 500 | Unexpected error |
Credential errors
How each host refuses a credential. The body is an OFREP error, { "errorCode": "PROVIDER_NOT_READY", "errorDetails": "…" }, with the flag's key on single-flag requests:
| Credential | flaggr.dev, and bulk on api.flaggr.dev | Single flag on api.flaggr.dev |
|---|---|---|
| None | 401 Authentication required | 401 Authentication required |
| Unknown, revoked, rotated or expired key | 403 with the reason, such as Invalid API token or API token has expired | 401 Invalid, revoked or expired API token |
| Personal access token | 403 Personal access tokens can't evaluate flags — use a project API token (SDK key) | 403 Forbidden: personal access tokens can't evaluate flags or call SDK endpoints — use a project API token (SDK key) |
| A key that couldn't be checked (the token store didn't answer) | 500 GENERAL | 401 API token couldn't be verified; retry: refused, but a retry may succeed |
Using with OpenFeature SDKs
Any OpenFeature OFREP provider works with Flaggr. Go and Python also have Flaggr's own SDKs: the Go SDK (github.com/flaggr-dev/flaggr-go) and the Python SDK (installed from GitHub; it isn't on PyPI). Use OFREP when your code already uses OpenFeature. Configure the provider with:
- Base URL
https://api.flaggr.dev/api. The providers append/ofrep/v1/evaluate/flags/{key}themselves, so a base URL that already ends in/ofrepor/ofrep/v1returns 404. - An
X-Service-Idheader naming the service. - The API token as a bearer token, read from an environment variable (
FLAGGR_TOKENbelow).
npm install @openfeature/server-sdk @openfeature/ofrep-providerimport { OpenFeature } from "@openfeature/server-sdk";
import { OFREPProvider } from "@openfeature/ofrep-provider";
await OpenFeature.setProviderAndWait(new OFREPProvider({
baseUrl: "https://api.flaggr.dev/api",
headers: [
["Authorization", `Bearer ${process.env.FLAGGR_TOKEN}`],
["X-Service-Id", "web-app"],
],
}));
const client = OpenFeature.getClient();
const enabled = await client.getBooleanValue("checkout-v2", false, { targetingKey: "user-123" });headers is a list of [name, value] pairs.
Without an X-Environment header, flags evaluate in development. To evaluate another environment, send X-Environment (for example production) the same way as X-Service-Id.
See the Python SDK and Go SDK pages for typed evaluation, evaluation context and framework setup.
Related
- Protocols — Protocol comparison (REST, Connect, gRPC, OFREP, SSE)
- REST API Reference — Native Flaggr evaluation endpoints
- Provider Architecture — Flaggr provider implementations