Skip to main content

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.

Vendor Neutral

OFREP means you can switch between flag providers without changing your application code. Any OFREP-compatible SDK works with Flaggr.

Endpoints

Single Flag Evaluation

POST/api/ofrep/v1/evaluate/flags/{key}Bearer token

Evaluate a single flag by key.

Headers:

HeaderRequiredDescription
X-Service-IdYesService identifier (or the serviceId query param; X-Flaggr-Service-Id is accepted as a legacy name)
X-EnvironmentNodevelopment, staging, production (or the environment query param; default: development)
AuthorizationYesBearer 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"
    }
  }' | jq

Bulk Evaluation

POST/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 a context of at most 128 attributes and 64 KiB. On api.flaggr.dev, a body over 128 KiB gets 413 PARSE_ERROR and more than 100 flags 400 INVALID_CONTEXT.
  • Credentials: without a Bearer token the answer is 401. A service that doesn't exist and one your credential can't read both get 403 PROVIDER_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 400 before its token is checked, also counts against the IP. Once an address has spent its IP allowance, every request from it gets 429 until the window resets, whatever token it sends, before the token is checked. 429 responses carry Retry-After, which browsers can read cross-origin. Through api.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

GET/api/ofrep/v1/metadata

Returns 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

ReasonDescription
STATICStatically configured value
DEFAULTDefault value returned
TARGETING_MATCHTargeting rule matched
SPLITVariant percentage split, or a running experiment's assignment
CACHEDCached evaluation result
DISABLEDFlag is disabled
ERROREvaluation error
UNKNOWNAny 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 CodeHTTP StatusWhen
PARSE_ERROR400Invalid JSON, or a missing or invalid flag key
PARSE_ERROR413On api.flaggr.dev: a request body over 128 KiB, answered at the edge before credentials are checked
INVALID_CONTEXT400Missing 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_CONTEXT413Single flag on api.flaggr.dev: a context over 128 attributes or 64 KiB
PROVIDER_NOT_READY401No 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_READY403A 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_FOUND404Single flag: the key doesn't exist (bulk lists it with errorCode instead)
PROVIDER_NOT_READY503, 504Single flag on api.flaggr.dev: the flag configuration couldn't be loaded in time; retry after Retry-After (flaggr.dev answers 500 GENERAL)
—429Rate 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
GENERAL500Unexpected 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:

Credentialflaggr.dev, and bulk on api.flaggr.devSingle flag on api.flaggr.dev
None401 Authentication required401 Authentication required
Unknown, revoked, rotated or expired key403 with the reason, such as Invalid API token or API token has expired401 Invalid, revoked or expired API token
Personal access token403 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 GENERAL401 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 /ofrep or /ofrep/v1 returns 404.
  • An X-Service-Id header naming the service.
  • The API token as a bearer token, read from an environment variable (FLAGGR_TOKEN below).
npm install @openfeature/server-sdk @openfeature/ofrep-provider
import { 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.