ToggleSmartly API Docs – Retrieve Feature Flags

Overview

The ToggleSmartly API allows you to retrieve feature flag values for your applications. All API requests require authentication via API keys, which you can generate from your dashboard.

Base URL

https://togglesmartly.com/api

Authentication

All API requests require an API key. Include your API key in the request body when making API calls.

Note: API keys are scoped to specific Organization, Application, and Environment combinations.

Get Feature Flag Values

Retrieve feature flag values for one or more feature flags. You can optionally filter by environment keys.

Endpoint

POST /api/v1/feature-flags/get-values

Full URL: https://togglesmartly.com/api/v1/feature-flags/get-values

Request Body

The request body must be JSON and include the following fields:

Field	Type	Required	Description
`api_key`	string	Yes	Your API key (generated from the dashboard)
`feature_flag_keys[]`	array of strings	Yes	Array of feature flag keys you want to retrieve
`env[]`	array of strings	No	Optional array of environment keys to filter results. If omitted, returns flags from all environments.

Request Example

{
  "api_key": "akey-12345678-1234-1234-1234-123456789012-abc123xyz789",
  "feature_flag_keys": [
    "enable_new_feature",
    "show_banner",
    "max_items_per_page"
  ],
  "env": ["production", "staging"]
}

Response Format

The API returns a JSON object with the following structure:

Field	Type	Description
`status`	integer	HTTP status code (200, 400, 401, 404, 429, 500)
`message`	string	Human-readable message describing the result
`data`	array	Array of feature flag value objects

Data Object Structure

Each item in the data array contains:

Field	Type	Description
`featureFlagKey`	string	The feature flag key
`env`	string	The environment key (e.g., "production", "staging")
`value`	string	The feature flag value (falls back to default value if flag value is null)

Success Response Example

200 OK

{
  "status": 200,
  "message": "Feature flags retrieved successfully.",
  "data": [
    {
      "featureFlagKey": "enable_new_feature",
      "env": "production",
      "value": "true"
    },
    {
      "featureFlagKey": "enable_new_feature",
      "env": "staging",
      "value": "false"
    },
    {
      "featureFlagKey": "show_banner",
      "env": "production",
      "value": "Welcome to our new site!"
    },
    {
      "featureFlagKey": "max_items_per_page",
      "env": "production",
      "value": "25"
    }
  ]
}

Error Responses

400 Bad Request - Invalid request format

{
  "status": 400,
  "message": "Invalid request. Please check your input.",
  "data": []
}

401 Unauthorized - Invalid or expired API key

{
  "status": 401,
  "message": "Invalid or expired API key.",
  "data": []
}

404 Not Found - No feature flags found or application not found

{
  "status": 404,
  "message": "No feature flags found matching the provided criteria.",
  "data": []
}

429 Too Many Requests - Rate limit exceeded

{
  "status": 429,
  "message": "Rate limit exceeded. Please try again later.",
  "data": []
}

500 Internal Server Error - Server error

{
  "status": 500,
  "message": "An internal server error occurred while retrieving feature flags.",
  "data": []
}

Rate Limiting

To ensure fair usage and prevent abuse, API requests are rate-limited per API key.

Rate Limits

Per API Key: 100 requests per minute
Global (per IP): 1000 requests per minute

When the rate limit is exceeded, you'll receive a 429 Too Many Requests response.

Best Practices

Cache feature flag values in your application
Implement exponential backoff for retries
Monitor your API usage to stay within limits
Use webhooks or polling strategies for real-time updates

Code Examples

Here are examples of how to call the API in different programming languages.

cURL

curl -X POST https://togglesmartly.com/api/v1/feature-flags/get-values \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "akey-12345678-1234-1234-1234-123456789012-abc123xyz789",
    "feature_flag_keys": ["enable_new_feature", "show_banner"],
    "env": ["production"]
  }'

JavaScript (Fetch API)

const response = await fetch('https://togglesmartly.com/api/v1/feature-flags/get-values', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    api_key: 'akey-12345678-1234-1234-1234-123456789012-abc123xyz789',
    feature_flag_keys: ['enable_new_feature', 'show_banner'],
    env: ['production']
  })
});

const data = await response.json();
console.log(data);

Python (requests)

import requests

url = 'https://togglesmartly.com/api/v1/feature-flags/get-values'
payload = {
    'api_key': 'akey-12345678-1234-1234-1234-123456789012-abc123xyz789',
    'feature_flag_keys': ['enable_new_feature', 'show_banner'],
    'env': ['production']
}

response = requests.post(url, json=payload)
data = response.json()
print(data)

C# (.NET)

using System.Net.Http;
using System.Text;
using System.Text.Json;

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, 
    "https://togglesmartly.com/api/v1/feature-flags/get-values");

var payload = new
{
    api_key = "akey-12345678-1234-1234-1234-123456789012-abc123xyz789",
    feature_flag_keys = new[] { "enable_new_feature", "show_banner" },
    env = new[] { "production" }
};

request.Content = new StringContent(
    JsonSerializer.Serialize(payload),
    Encoding.UTF8,
    "application/json"
);

var response = await client.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();
var data = JsonSerializer.Deserialize<dynamic>(responseBody);

PHP

$url = 'https://togglesmartly.com/api/v1/feature-flags/get-values';
$payload = [
    'api_key' => 'akey-12345678-1234-1234-1234-123456789012-abc123xyz789',
    'feature_flag_keys' => ['enable_new_feature', 'show_banner'],
    'env' => ['production']
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

Getting Started

Step 1: Generate an API Key

Log in to your ToggleSmartly dashboard
Navigate to Settings → API Keys
Click "Add API Key"
Select your Organization, Application, and Environment
Copy the generated API key (you won't be able to see it again!)

Step 2: Make Your First API Call

Use the API key in your request payload
Specify the feature flag keys you want to retrieve
Optionally filter by environment keys
Handle the response and use the feature flag values in your application

Important Notes

API Key Security: Never expose your API keys in client-side code or public repositories. Store them securely as environment variables.
API Key Scope: Each API key is scoped to a specific Organization, Application, and Environment combination. You can only retrieve feature flags that belong to that scope.
Active Flags Only: The API only returns feature flags that are marked as active. Inactive flags are excluded from results.
Environment Filtering: If you don't specify environment keys, the API returns feature flags from all active environments for the application.
Value Fallback: If a feature flag's value is null, the API returns the default value. If both are null, an empty string is returned.
Rate Limiting: Be mindful of rate limits. Implement caching and retry logic with exponential backoff.

API Documentation