Core API

The Core API is used for evaluating feature flags in your applications. This lightweight API is optimized for performance and designed to be called directly from your client-side or server-side applications.

Base URL

All Core API requests should be made to:

https://core.fecusio.com/v1

Authentication

Authentication is done using the X-Environment-Key header. You can use either a public or private environment key depending on your use case:

Private environment key: Use for server-side applications (backend services)
Public environment key: Use for client-side applications (web, mobile)

X-Environment-Key: YOUR_ENVIRONMENT_KEY

Obtaining Environment Key

To obtain an API key for a workspace, navigate to Integration page from workspace Settings page. Under “Environment keys” tab you will see list of public and private keys for each environment.

Flag Evaluation

When you evaluate flags you can either provide identities context, or evaluate without identities context.

When you do not provide the context, you will get the default flag values for the entire environment.

When you do provide context it will take identity overrides into consideration.

Endpoint

POST /evaluate

Request Format

{
  "identities": ["01k09xczdrq1pe2b9hcweszaaq", "01k09xczdwh5syw4env5wxmw7p"]
}

You can also send empty request body, which will return the default flag values for the entire environment. Including identities enables context-aware flag evaluation.

Response Format

The API returns a JSON response with flag states in the following format:

{
  "data": {
    "my_feature_1": { "enabled": true },
    "my_feature_2": { "enabled": false },
    "my_feature_3": { "enabled": true }
  }
}

Each flag is represented by its key and includes an enabled property indicating whether the flag is enabled for the current context.

Error Handling

When errors occur, the API will respond with an appropriate HTTP status code and error details:

{
  "message": "Human-readable error message"
}

Example

Let’s say you have three feature flags set up, “Email Automation”, Email Scheduling” and “Advanced Analytics”. You also have Starter identity, which represents a billing plan in your app, and you have Alicia identity, which represents a person (user) in your app. Alicia is subscribed to Starter plan in your app.

When doing evaluation, you will send following request:

{
  "identities": ["starter_plan_identity_id", "alicia_identity_id"]
}

Following table shows flags configuration (along with the identity overrides) in your app, and the final evaluation outcome in this case:

Identity	Email Automation	Email Scheduling	Advanced Analytics
Environment Default	Enabled	Enabled	Enabled
Starter (override)	-	Disabled	Disabled
Alicia (override)	-	-	Enabled
Evaluation	Enabled	Disabled	Enabled

In this example:

Both feature flags have a default value of “enabled” at the environment level
Starter plan has overridden both flags to “disabled”
Alicia has only overridden “Advanced Analytics” to “enabled” (which matches the default, but explicitly enforces it)
In the hierarchy, for Email Automation there are no overrides, so the default environment value is the outcome. For Email Scheduling first encountered override is from Starter plan identity, so the value of that override is the outcome. For Advanced Analytics, first encountered override is from Alicia user identity, so the value of that override is the outcome.

Best Practices

Cache flag values: For high-traffic applications, consider implementing a caching strategy to reduce API calls
Error handling: Always implement proper error handling to ensure your application works even when the API is unavailable
Rate limiting: The API is rate-limited to protect our services; implement exponential backoff in case of rate limiting errors