Skip to main content

Feature Toggles

Explore the API
Launch the OpenAPI Explorer to browse the live REST specs, inspect request and response schemas, and execute calls against your environment with an API key.

The Feature Toggles API enables programmatic access to feature flag management, overrides, and status checks. Use these endpoints to integrate feature toggles into your applications and workflows.

Base URL​

/api/feature_toggles

Authentication​

All Feature Toggles API endpoints require authentication. Include your API key or session token in the request headers.

Note: All admin-related endpoints require the Super Admin role. The check endpoint only requires authentication.

curl -X GET "$BASE_URL/feature_toggles/global" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

Multi-Tenant Scoping​

All endpoints are automatically scoped to your tenant based on your authentication context. You cannot access toggles or overrides from other tenants unless explicitly authorized.

export BASE_URL="http://localhost:3000/api"
export API_KEY="<paste your API key secret here>"

Use an API key with appropriate permissions for feature toggle management.

Global​

List Global Toggles — GET /feature_toggles/global​

Query parameters (selected):

  • page, pageSize — pagination (default 1, 50).
  • search — case-insensitive match on identifier, name, description, category.
  • category — filter by category.
  • name — filter by name.
  • identifier — filter by identifier.
  • type — filter by toggle type (boolean, string, number, json).
  • sortField — id, category, identifier, name, createdAt, updatedAt, type.
  • sortDir — asc, desc.
curl -X GET "$BASE_URL/feature_toggles/global?page=1&pageSize=50" \
  -H "X-Api-Key: $API_KEY" \
  -H "Accept: application/json"

Response:

{
  "items": [
    {
      "id": "uuid-of-toggle",
      "identifier": "new-feature",
      "name": "New Feature",
      "description": "Description of the new feature",
      "category": "experimental",
      "type": "boolean",
      "defaultValue": false,
      "created_at": "2025-12-29 21:59:25.246+00",
      "updated_at": "2025-12-29 21:59:25.246+00"
    }
  ],
  "total": 1,
  "totalPages": 1,
  "page": 1,
  "pageSize": 50
}

Get Global Toggle — GET /feature_toggles/global/{id}​

Get details of a specific feature toggle.

curl -X GET "$BASE_URL/feature_toggles/global/$TOGGLE_ID" \
  -H "X-Api-Key: $API_KEY" \
  -H "Accept: application/json"

Response:

{
  "id": "uuid-of-toggle",
  "identifier": "new-feature",
  "name": "New Feature",
  "description": "Description of the new feature",
  "category": "experimental",
  "type": "boolean",
  "defaultValue": false,
  "created_at": "2025-12-29 21:59:25.246+00",
  "updated_at": "2025-12-29 21:59:25.246+00"
}

Create Global Toggle — POST /feature_toggles/global​

Body must satisfy toggleCreateSchema:

  • Required: identifier (lowercase, numbers, underscores), name, type (boolean, string, number, json).
  • Optional: description, category, defaultValue (any, defaults to null).
curl -X POST "$BASE_URL/feature_toggles/global" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "new-feature",
    "name": "New Feature",
    "description": "Description of the new feature",
    "category": "experimental",
    "type": "boolean",
    "defaultValue": false
  }'

Response:

{ "id": "uuid-of-new-toggle" }

Update Global Toggle — PUT /feature_toggles/global​

Send id and any mutable fields from the create schema.

  • Required: id.
  • Optional: identifier, name, description, category, defaultValue.
curl -X PUT "$BASE_URL/feature_toggles/global" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "uuid-of-toggle",
    "name": "Updated Feature Name",
    "defaultValue": true
  }'

Response:

{ "id": "uuid-of-toggle" }

Delete Global Toggle — DELETE /feature_toggles/global​

Delete a feature toggle.

  • Required: id (in body).
curl -X DELETE "$BASE_URL/feature_toggles/global" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "uuid-of-toggle"
  }'

Response:

{ "id": "uuid-of-toggle" }

Global Specific Override — GET /feature_toggles/global/{id}/override​

Query parameters:

  • No parameters required.

Get specific override for a feature toggle in current tenant context.

# Get override for a specific toggle
curl -X GET "$BASE_URL/feature_toggles/global/$TOGGLE_ID/override" \
  -H "X-Api-Key: $API_KEY" \
  -H "Accept: application/json"

Response:

{
  "id": "uuid-of-override",
  "value": true,
  "tenantName": "Tenant Name",
  "tenantId": "uuid-of-tenant",
  "toggleType": "boolean"
}

Overrides​

List All Overrides — GET /feature_toggles/overrides​

Query parameters:

  • page, pageSize — pagination (default 1, 25).
  • category — filter by category.
  • name — filter by name.
  • identifier — filter by identifier.
  • sortField - identifier, name, category.
  • sortDir — asc, desc.
curl -X GET "$BASE_URL/feature_toggles/overrides?page=1&pageSize=50" \
  -H "X-Api-Key: $API_KEY" \
  -H "Accept: application/json"

Response:

{
  "items": [
    {
      "id": "uuid-of-override",
      "toggleId": "uuid-of-toggle",
      "tenantId": "uuid-of-tenant",
      "identifier": "new-feature",
      "name": "New Feature",
      "category": "experimental",
      "tenantName": "Tenant Name",
      "isOverride": true
    }
  ],
  "total": 1,
  "totalPages": 1,
  "page": 1,
  "pageSize": 50,
  "isSuperAdmin": false
}

Update Override — PUT /feature_toggles/overrides​

Change the state of a feature toggle override.

  • Required: toggleId, isOverride (boolean).
  • Optional: overrideValue (any).

Note: The tenantId is automatically resolved from the request context.

curl -X PUT "$BASE_URL/feature_toggles/overrides" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toggleId": "uuid-of-toggle",
    "isOverride": true,
    "overrideValue": true
  }'

Response:

{
  "ok": true,
  "overrideToggleId": "uuid-of-override"
}

Check​

Check if a feature is enabled and get its configuration value for the current context.

Check Boolean Feature — GET /feature_toggles/check/boolean​

Query parameters:

  • identifier — (required) feature toggle identifier.
curl -X GET "$BASE_URL/feature_toggles/check/boolean?identifier=new-feature" \
  -H "X-Api-Key: $API_KEY" \
  -H "Accept: application/json"

Response:

{
  "enabled": true,
  "source": "override",
  "toggleId": "uuid-of-toggle",
  "identifier": "new-feature",
  "tenantId": "uuid-of-tenant"
}

Check String Feature — GET /feature_toggles/check/string​

Query parameters:

  • identifier — (required) feature toggle identifier.
curl -X GET "$BASE_URL/feature_toggles/check/string?identifier=my-string-feature" \
  -H "X-Api-Key: $API_KEY" \
  -H "Accept: application/json"

Response:

{
  "valueType": "string",
  "value": "some-string-value",
  "source": "default",
  "toggleId": "uuid-of-toggle",
  "identifier": "my-string-feature",
  "tenantId": "uuid-of-tenant"
}

Check Number Feature — GET /feature_toggles/check/number​

Query parameters:

  • identifier — (required) feature toggle identifier.
curl -X GET "$BASE_URL/feature_toggles/check/number?identifier=my-number-feature" \
  -H "X-Api-Key: $API_KEY" \
  -H "Accept: application/json"

Response:

{
  "valueType": "number",
  "value": 42,
  "source": "default",
  "toggleId": "uuid-of-toggle",
  "identifier": "my-number-feature",
  "tenantId": "uuid-of-tenant"
}

Check JSON Feature — GET /feature_toggles/check/json​

Query parameters:

  • identifier — (required) feature toggle identifier.
curl -X GET "$BASE_URL/feature_toggles/check/json?identifier=my-json-feature" \
  -H "X-Api-Key: $API_KEY" \
  -H "Accept: application/json"

Response:

{
  "valueType": "json",
  "value": { "key": "value" },
  "source": "default",
  "toggleId": "uuid-of-toggle",
  "identifier": "my-json-feature",
  "tenantId": "uuid-of-tenant"
}