Runtime API
Introduction to Reflag Runtime API
What is the Runtime API?
The Reflag Runtime API uses JSON over HTTP. It lets browsers and backend services access flag data and share companies, users, and events.
Authentication
To start, you need to obtain either a publishable or secret SDK key from within your Reflag app settings.
Publishable keys can be passed in the Authorization header using the bearer scheme, or as a query parameter when calling the Runtime API. Secret keys can only be passed in the Authorization header:
// using headers
Authorization: Bearer <secret_or_publishable_key>
// using query argument
GET /features/enabled?publishableKey=<publishable_key>Global Infrastructure
The Runtime API currently resides at https://front.reflag.com/ and https://front-eu.reflag.com.
Requests to the front-facing API are automatically routed to a data center near you and should thus have a relatively low latency regardless of where your customers are located.
API Endpoints
This section provides a streamlined overview of the API endpoints available through Reflag. Each endpoint is listed with its requirement for either a publishable or secret key, and a brief description of its functionality.
GET /features
Retrieve all features with their respective access rules
GET /features/evaluated
Retrieve features that are evaluated for the provided user/company
GET /features/enabled
Retrieve features that are enabled for the provided user/company
POST /features/events
Send events related to feature access
POST /user
Update user in Reflag
POST /company
Update company in Reflag
POST /event
Send events related to feature usage or user actions
POST /bulk
Send multiple calls in bulk.
GET /features
This endpoint provides a complete list of flags along with their targeting rules. It's particularly useful for backend SDKs that need to retrieve and evaluate these rules locally. This approach enables determining which flags to activate for a specific user or company, eliminating the need to repeatedly call the features/enabled endpoint for each user or company.
Example
GET /features/evaluated
This endpoint retrieves a list of flag values evaluated for a particular user or company.
Send the context in one query parameter called contextJson. Use JSON.stringify() to turn the whole context into JSON text, then URLSearchParams to encode it for the URL. Arrays stay as arrays:
The context can include user, company, and other objects. None of these objects is required. User and company IDs are also optional; if provided, they must be strings or numbers, not arrays.
Context attributes can hold strings, numbers, true/false values, null, or arrays. You can group attributes in one nested object—for example, user.profile.roles, targeted with the same dotted path. Deeper object nesting is rejected.
By default, the JSON text can be up to 16,384 bytes before URL encoding. Your HTTP server or proxy may have a lower URL limit.
The API returns a validation error if:
The JSON is not valid or the context does not follow the rules above.
You send
contextJsonmore than once.You send
contextJsontogether withcontextorcontext.*parameters.
The older query format still works for single values, such as context.company.id=42&context.user.id=99. For arrays, use contextJson; do not send separate items as context.user.roles.0=admin.
Example using the older query format
Evaluation errors
Flag results may include evaluationErrors:
MISSING_CONTEXT_FIELD: a rule needs a field that was not provided.UNSUPPORTED_ARRAY_OPERATOR: a rule tried to use an operator that does not work with arrays.
The affected rule does not match, but the API still returns a normal response and other rules can match. Errors while choosing a config value are listed in config.evaluationErrors.
Older clients can still use missingContextFields, which lists missing fields only. Use evaluationErrors for new integrations.
See array attribute operators for supported operators and examples.
GET /features/enabled
This endpoint is similar to features/evaluated but only includes flags that have been evaluated as true. It accepts the same contextJson parameter.
POST /features/events
This endpoint is designed to relay flag "check" events for various functions within the Reflag. Check events automatically generated by Reflag SDKs when user code checks if a specific flag is activated.
Example
POST /user
User Endpoint Documentation
This endpoint is designed to track individual users within your application. It will create a new user if one doesn't exist or update existing users if their IDs were previously recorded.
Unique ID: Use a stable unique identifier, such as a database ID or a stable hash, to reference users.
User Attributes: You can include additional attributes for the user.
Expected Body
userId
String
attributes
Object
timestamp
ISO 8601
Example
POST /company
This endpoint is designed to track individual companies (organizations) within your application. It will create a new company if one doesn't exist, or update existing companies if their IDs were previously recorded.
Unique ID: Use a stable unique identifier, such as a database ID or a stable hash, to reference companies.
Company Attributes: You can include additional attributes for the company.
User ID: You can associate a user with a company by providing the
userId. This is important as flags in Reflag look at company-level data.
Expected Body
companyId
String
attributes
Object
timestamp
ISO 8601 String
userId
String
Example
To monitor which companies have Slack enabled, set has_slack_enabled: true for the desired companies. Then, create a flag in Reflag that uses has_slack_enabled attribute in its targeting rules.
POST /event
In your application, events help you monitor user interactions. It's recommended to focus on a few essential features and those under development. To track an event, invoke this method during user interaction.
In general, event names match the keys associated with your flags, allowing Reflag to align these events with the specific flag guarding the triggered code. However, when needed, you can utilize custom events for more tailored workflows.
Request Body
event
String
userId
String
companyId
String
attributes
Object
timestamp
ISO 8601
Example
POST Feedback
Submit qualitative feedback on a specific feature to complement your quantitative metrics. Collect a 1-5 satisfaction score, qualitative feedback, or both.
Request Body
featureId
String
userId
String
companyId
String
score
Number (1-5)
comment
String
Example
Array attributes
You can send arrays in the attributes of user, company, and event requests, including bulk requests. Send "roles": ["admin", "editor"], not "roles": "[\"admin\",\"editor\"]".
An update replaces the whole list; sending [] clears it. Each array stays one attribute, rather than becoming separate fields such as roles.0.
See array attribute operators for matching rules and examples.
Responses
The API returns a 200 status code for successful calls and a 400 status code for errors, including invalid request bodies.
A 403 response indicates that the provided publishable or secret keys are invalid or not allowed with this endpoint.
If you encounter a 500 status code, retry the request. Sending events to Reflag might result in duplicate entries, but this is rare.
Further Documentation
For a comprehensive overview of the available Runtime API endpoints, refer to the API Reference section.
Last updated
Was this helpful?