openapi: 3.1.0 servers: - url: / info: version: 0.3.0 title: OpenFeature Remote Evaluation Protocol (OFREP) description: | --- The **OpenFeature Remote Evaluation Protocol (OFREP)** is an API specification for feature flagging that enables vendor-agnostic communication between applications and flag management systems. OFREP defines a standard API layer between OpenFeature providers and flag management systems, allowing any flag management system to implement the protocol and be compatible with community-maintained providers. For more information, see the [OFREP documentation](https://openfeature.dev/docs/reference/other-technologies/ofrep/). contact: url: https://github.com/open-feature/protocol license: identifier: Apache-2.0 name: Apache 2.0 security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: OFREP Core description: | **Required**: Core APIs to implement to support OFREP. *This is the minimum set of APIs required for a flag management system to be OFREP compatible.* paths: /ofrep/v1/evaluate/flags/{key}: post: tags: [OFREP Core] summary: Evaluate A Single Feature Flag description: | Evaluates a single feature flag by its key. This endpoint is used by **server-side providers** for dynamic context evaluation, where each evaluation request includes the evaluation context. The endpoint returns the evaluated flag value along with metadata including the evaluation reason, variant, and any flag-specific metadata. The flag value can be one of several types: boolean, string, integer, float, object, or a code default (indicating the provider should use the code default value). **Use Case**: Server-side applications where evaluation context may change between requests and real-time targeting decisions are required. operationId: evaluateFlag parameters: - name: key in: path required: true description: The unique identifier (key) of the feature flag schema: type: string example: discount-banner requestBody: required: true description: Evaluation request containing the context for flag evaluation content: application/json: schema: $ref: "#/components/schemas/evaluationRequest" example: context: targetingKey: user-123 email: user@example.com custom-plan: premium country: CA responses: "200": description: Successful flag evaluation. Returns the evaluated flag value with metadata. content: application/json: schema: $ref: "#/components/schemas/serverEvaluationSuccess" example: key: discount-banner value: true reason: TARGETING_MATCH variant: enabled "400": description: Bad evaluation request. The request is malformed or contains invalid context. content: application/json: schema: $ref: "#/components/schemas/evaluationFailure" example: key: my-flag errorCode: INVALID_CONTEXT errorDetails: "Context is missing required targetingKey property" "404": description: Flag not found. The specified flag key does not exist in the flag management system. content: application/json: schema: $ref: "#/components/schemas/flagNotFound" example: key: non-existent-flag errorCode: FLAG_NOT_FOUND errorDetails: "Flag 'non-existent-flag' was not found" "401": description: Unauthorized. Authentication credentials are missing, invalid, or expired. "403": description: Forbidden. The client does not have permission to access the requested resource. "429": description: Too Many Requests. Rate limit has been exceeded. headers: Retry-After: description: | Indicates when to retry the request again. Can be either a date-time string or a number of seconds to wait. schema: type: string format: date-time example: "2024-02-07T12:00:00Z" "500": description: Internal Server Error. An unexpected error occurred on the server that prevented flag evaluation. content: application/json: schema: $ref: "#/components/schemas/generalErrorResponse" example: errorDetails: "An internal server error occurred while processing the request" /ofrep/v1/evaluate/flags: post: tags: [OFREP Core] summary: Bulk Evaluate All Feature Flags description: | Evaluates all feature flags in a single request using a static context. This endpoint is used by **client-side providers** for static context evaluation, where all flags are evaluated once and then cached locally for subsequent use. The endpoint returns an array of all flag evaluations, where each flag can be either a successful evaluation or an evaluation failure. The response includes an ETag header for cache validation, allowing clients to use the `If-None-Match` header to avoid unnecessary re-evaluation when flags haven't changed. operationId: evaluateFlagsBulk parameters: - in: header name: If-None-Match description: | Optional ETag value from a previous bulk evaluation response. If provided and the ETag matches the current flag set, the server will return a 304 Not Modified response, indicating that flags haven't changed since the last evaluation. schema: type: string required: false example: abc123xyz - $ref: "#/components/parameters/flagConfigEtag" - $ref: "#/components/parameters/flagConfigLastModified" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/bulkEvaluationRequest" example: context: targetingKey: user-456 email: user@example.com plan: free country: CA responses: "200": description: Successful bulk evaluation. headers: ETag: schema: type: string description: | Entity tag (ETag) representing the current state of all flags. Clients should include this value in subsequent requests using the `If-None-Match` header for cache validation. example: abc123xyz content: application/json: schema: $ref: "#/components/schemas/bulkEvaluationSuccess" example: flags: - key: discount-banner value: true reason: TARGETING_MATCH variant: enabled - key: theme-color value: "blue" reason: STATIC variant: default - key: non-existent-flag errorCode: FLAG_NOT_FOUND errorDetails: "Flag 'non-existent-flag' was not found" eventStreams: - type: sse url: https://sse.example.com/event-stream?channels=env_abc123_v1 inactivityDelaySec: 120 metadata: version: v12 "304": description: | Not Modified. The flags haven't changed since the last evaluation (ETag matches). No response body is returned. "400": description: Bad evaluation request. The request is malformed or contains invalid context. content: application/json: schema: $ref: "#/components/schemas/bulkEvaluationFailure" example: errorCode: INVALID_CONTEXT errorDetails: "Context is missing required targetingKey property" "401": description: Unauthorized. Authentication credentials are missing, invalid, or expired. "403": description: Forbidden. The client does not have permission to access the requested resource. "429": description: Too Many Requests. Rate limit has been exceeded. headers: Retry-After: description: | Indicates when to retry the request again. Can be either a date-time string or a number of seconds to wait. schema: oneOf: - type: string format: date-time - type: integer description: Number of seconds to wait before retrying example: "2024-02-07T12:00:00Z" "500": description: Internal server error. An unexpected error occurred on the server that prevented flag evaluation. content: application/json: schema: $ref: "#/components/schemas/generalErrorResponse" example: errorDetails: "An internal server error occurred while processing the request" components: securitySchemes: BearerAuth: description: | Optional Bearer token authentication. If supported by the flag management system, clients can authenticate using a Bearer token in the `Authorization` header following the format: `Authorization: Bearer `. type: http scheme: bearer bearerFormat: JWT ApiKeyAuth: description: | Optional API key authentication. If supported by the flag management system, clients can authenticate by providing an API key in the `X-API-Key` header. type: apiKey in: header name: X-API-Key parameters: flagConfigEtag: in: query name: flagConfigEtag description: | Optional ETag metadata provided by an event stream for change-triggered re-fetches (see ADR-0008). This is not a standard HTTP conditional request header; it is metadata for server-side cache validation and freshness checks. It should only be included when the request is directly triggered by a received change notification event. schema: type: string required: false example: 550e8400-e29b-41d4-a716-446655440000 flagConfigLastModified: in: query name: flagConfigLastModified description: | Optional last-modified metadata provided by an event stream for change-triggered re-fetches (see ADR-0008). Supports Unix timestamp in seconds (recommended) or an ISO 8601 date-time string, and is transported as query metadata rather than `If-Modified-Since`. It should only be included when the request is directly triggered by a received change notification event. schema: oneOf: - type: integer minimum: 0 - type: string format: date-time required: false examples: epochSeconds: value: 1771622898 isoDate: value: "2026-02-20T21:28:18Z" schemas: bulkEvaluationRequest: description: | Request body for bulk flag evaluation. Contains a static context that will be used to evaluate all flags. type: object required: - context properties: context: $ref: "#/components/schemas/context" bulkEvaluationSuccess: description: | Success response for bulk flag evaluation. Contains an array of flag evaluations, where each item can be either a successful evaluation or an evaluation failure. This allows partial success scenarios where some flags may fail while others succeed. type: object required: - flags properties: flags: type: array description: Array of flag evaluations. Each evaluation can be a success or failure. items: oneOf: - $ref: "#/components/schemas/evaluationSuccess" - $ref: "#/components/schemas/evaluationFailure" metadata: $ref: "#/components/schemas/metadata" description: | Arbitrary metadata for the flag set, useful for telemetry and documentary purposes. eventStreams: type: array description: | Optional array of real-time change notification connections. When present, the provider should connect to any entries with a known type and re-fetch flag evaluations when notified of changes. If not present, the provider should continue using polling for change detection. Entries with unknown types must be ignored for forward compatibility. items: $ref: "#/components/schemas/eventStream" bulkEvaluationFailure: description: | Failure response for bulk evaluation. Returned when the entire bulk evaluation request fails (e.g., invalid context, parse errors). Individual flag failures within a successful bulk evaluation are represented as evaluationFailure items in the flags array. type: object properties: errorCode: type: string description: | An error code specific to the bulk evaluation error. See https://openfeature.dev/specification/types#error-code for error code definitions. example: INVALID_CONTEXT errorDetails: type: string description: Optional error details description for logging or debugging purposes example: "Context is missing required targetingKey property" required: - errorCode evaluationRequest: description: | Request body for single feature flag evaluation. Contains the evaluation context that will be used to evaluate the feature flag. type: object required: - context properties: context: $ref: "#/components/schemas/context" serverEvaluationSuccess: allOf: - $ref: "#/components/schemas/evaluationSuccess" eventStream: description: | A real-time change notification connection endpoint. The `type` field identifies the push mechanism; currently only `sse` is defined. Providers must ignore entries with unknown types for forward compatibility. Exactly one of `url` or `endpoint` must be provided. type: object required: - type oneOf: - required: - url not: required: - endpoint - required: - endpoint not: required: - url properties: type: type: string description: | The connection type identifying the push mechanism to use. Currently only `sse` is defined. Providers must ignore entries with unknown types for forward compatibility. example: "sse" url: type: string format: uri description: | The endpoint URL the client should connect to for real-time flag change notifications. This is the default representation and is opaque to the provider. The URL may include authentication tokens, channel identifiers, or other query parameters as needed by the vendor's infrastructure. Implementations must treat this value as sensitive and must not log or persist the full URL including its query string. example: "https://sse.example.com/event-stream?channels=env_abc123_v1" endpoint: $ref: "#/components/schemas/eventStreamEndpoint" inactivityDelaySec: type: integer minimum: 1 default: 120 description: | Number of seconds of client inactivity (e.g., browser tab hidden, mobile app backgrounded) after which the connection should be closed to conserve resources. The client must reconnect and perform a full unconditional re-fetch when activity resumes. When determining the effective inactivity timeout, providers should use a client-side override if configured; otherwise use this value when present; otherwise default to 120 seconds. example: 120 eventStreamEndpoint: type: object required: - requestUri description: | Structured endpoint components for deployments that need to override the origin cleanly while preserving the request target. When present, providers construct the connection URL as `origin + requestUri`. If `origin` is absent, providers should use their configured OFREP base URL origin. properties: origin: type: string format: uri description: | The scheme + host + optional port portion of the endpoint URL. If absent, providers should use their configured OFREP base URL origin. example: "https://sse.example.com" requestUri: type: string pattern: "^/" description: | The path + query portion of the endpoint URL. Must start with `/`. example: "/event-stream?channels=env_abc123_v1" sseEvent: description: | Schema for a single Server-Sent Event in the flag configuration change notification stream. The `data` field contains a JSON-encoded payload that providers must parse to determine the event type and any metadata. type: object required: - data properties: data: type: string description: | JSON-encoded event payload. Providers must parse this string as JSON and inspect the `type` field to determine behavior. contentMediaType: application/json contentSchema: $ref: "#/components/schemas/sseEventData" event: type: string description: | The SSE event type. Always `message` for OFREP events. Providers must inspect `data.type` rather than this field for event routing. example: "message" id: type: string description: | Event identifier used by SSE clients for resume semantics via `Last-Event-ID`. example: "evt-1234" retry: type: integer minimum: 0 description: | Reconnection time in milliseconds suggested by the server. sseEventData: description: | JSON payload inside the event `data` field. The `type` field determines the event semantics. Providers must handle `refetchEvaluation` and ignore unknown values for forward compatibility. type: object required: - type properties: type: type: string description: | The OFREP event type. Currently only `refetchEvaluation` is defined. Providers must ignore unknown values for forward compatibility. example: "refetchEvaluation" etag: type: string description: | Latest flag configuration cache validation token. If present, providers should include it as the `flagConfigEtag` query parameter on the re-fetch request. example: abc123 lastModified: description: | Latest flag configuration timestamp. Supports Unix timestamp in seconds (recommended) or an ISO 8601 date-time string. If present, providers should include it as the `flagConfigLastModified` query parameter on the re-fetch request. oneOf: - type: integer minimum: 0 - type: string format: date-time example: 1771622898 evaluationSuccess: description: | Successful feature flag evaluation response. The value property is present for all flag types except `codeDefaultFlag`, which indicates the provider should use the code default value. type: object required: - key - reason allOf: - properties: key: $ref: "#/components/schemas/key" reason: type: string description: | An OpenFeature reason code indicating why the flag was evaluated to this value. See https://openfeature.dev/specification/types/#resolution-reason for reason code definitions. enum: [STATIC, TARGETING_MATCH, SPLIT, DISABLED, UNKNOWN] variant: type: string description: | Variant identifier for the evaluated feature flag value. Represents a specific variation or configuration of the feature flag. metadata: allOf: - $ref: "#/components/schemas/metadata" - $ref: "#/components/schemas/flagMetadataDescription" - $ref: "#/components/schemas/flagMetadataExamples" - oneOf: - $ref: "#/components/schemas/booleanFlag" - $ref: "#/components/schemas/stringFlag" - $ref: "#/components/schemas/integerFlag" - $ref: "#/components/schemas/floatFlag" - $ref: "#/components/schemas/objectFlag" - $ref: "#/components/schemas/codeDefaultFlag" evaluationFailure: description: | Feature flag evaluation failure response. Returned when a feature flag evaluation fails, such as when the context is invalid, required targeting keys are missing, or parsing errors occur. type: object properties: key: $ref: "#/components/schemas/key" errorCode: type: string description: | OpenFeature compatible error code indicating the type of error. See https://openfeature.dev/specification/types#error-code for error code definitions. enum: [PARSE_ERROR, TARGETING_KEY_MISSING, INVALID_CONTEXT, GENERAL] errorDetails: $ref: "#/components/schemas/errorDetails" metadata: allOf: - $ref: "#/components/schemas/metadata" - $ref: "#/components/schemas/flagMetadataDescription" - $ref: "#/components/schemas/flagMetadataExamples" required: - key - errorCode flagNotFound: description: | Feature flag not found response. Returned when a requested feature flag key does not exist in the flag management system. This can be an expected response in certain flag management systems. This is distinct from evaluation failures, which occur when a flag exists but cannot be evaluated. type: object properties: key: $ref: "#/components/schemas/key" errorCode: type: string description: Error code indicating the flag was not found enum: [FLAG_NOT_FOUND] errorDetails: $ref: "#/components/schemas/errorDetails" metadata: allOf: - $ref: "#/components/schemas/metadata" - $ref: "#/components/schemas/flagMetadataDescription" - $ref: "#/components/schemas/flagMetadataExamples" required: - key - errorCode generalErrorResponse: description: | General error response for unexpected server errors (500 status). Used when the server encounters an internal error that prevents flag evaluation. type: object properties: errorDetails: $ref: "#/components/schemas/errorDetails" key: type: string description: | The unique identifier (key) of the feature flag. This is used to reference a specific flag in the flag management system. example: discount-banner context: type: object description: | Evaluation context containing information used to evaluate feature flags. The context includes a `targetingKey` (required) along with additional properties such as user attributes, session data, or request metadata that can be used for targeting rules. required: - targetingKey properties: targetingKey: type: string additionalProperties: true example: targetingKey: user-123 email: user@example.com plan: premium country: CA booleanFlag: description: A boolean typed flag value. Used for simple on/off feature flags. type: object properties: value: type: boolean required: - value stringFlag: description: A string typed flag value. type: object properties: value: type: string required: - value integerFlag: description: An integer typed flag value. type: object properties: value: type: integer required: - value floatFlag: description: A float typed flag value. type: object properties: value: type: number format: float required: - value objectFlag: description: An object typed flag value. type: object properties: value: type: object additionalProperties: true required: - value codeDefaultFlag: description: | A flag evaluation that defers to the code default value. When a flag evaluation returns this type, it indicates that the provider should use the default value specified in the application code rather than a value from the flag management system. **Note**: This schema has no `value` property. The provider must use the code default value when processing this response. type: object properties: {} errorDetails: type: string description: | A human-readable error description providing additional context about the evaluation failure. Useful for logging, debugging, and monitoring purposes. metadata: type: object description: | Arbitrary metadata object that can contain any additional information about flags or flag sets. This metadata is useful for debugging and telemetry purposes. additionalProperties: oneOf: - type: boolean - type: string - type: number flagMetadataExamples: description: Example metadata structure for flags example: team: ecommerce businessPurpose: experiment owner: "product-team" flagMetadataDescription: description: | Arbitrary metadata for the flag, useful for telemetry and documentary purposes.