API beta
GrowthBook offers a full REST API for interacting with the GrowthBook application. This is currently in beta as we add more authenticated API routes and features.
Request data can use either JSON or Form data encoding (with proper Content-Type
headers). All response bodies are JSON-encoded.
The API base URL for GrowthBook Cloud is https://api.growthbook.io
. For self-hosted deployments, it is the same as your API_HOST environment variable (defaults to http://localhost:3100
). The rest of these docs will assume you are using GrowthBook Cloud.
Authentication
We support both the HTTP Basic and Bearer authentication schemes for convenience.
You first need to generate a new Secret Key in GrowthBook by going to Settings -> API Keys
.
If using HTTP Basic auth, pass the Secret Key as the username and leave the password blank:
curl https://api.growthbook.io/api/v1 \
-u secret_abc123DEF456:
# The ":" at the end stops curl from asking for a password
If using Bearer auth, pass the Secret Key as the token:
curl https://api.growthbook.io/api/v1 \
-H "Authorization: Bearer secret_abc123DEF456"
Errors
The API may return the following error status codes:
- 400 - Bad Request - Often due to a missing required parameter
- 401 - Unauthorized - No valid API key provided
- 402 - Request Failed - The parameters are valid, but the request failed
- 403 - Forbidden - Provided API key does not have the required access
- 404 - Not Found - Unknown API route or requested resource
- 429 - Too Many Requests - You exceeded the rate limit of 60 requests per minute. Try again later.
- 5XX - Server Error - Something went wrong on GrowthBook's end (these are rare)
The response body will be a JSON object with the following properties:
- message - Information about the error
Pagination
All list methods are paginated and support the querystring parameters:
limit
- number to return, between 1 and 100, default10
offset
- how many to skip, default0
For example:
curl -G https://api.growthbook.io/api/v1/features \
-u secret_abc123DEF456:
-d limit=5
-d offset=10
# Return features 11-15
And the response will contain the fields:
limit
- The limit used for the current requestoffset
- The offset used for the current requestcount
- Number returned in the responsetotal
- Total number of itemshasMore
-true
if there is another page,false
if there are no more itemsnextOffset
- Offset to fetch the next page, ornull
if there are no more results
Features
The Feature Object
This object represents a single feature in your account. Features are complex objects with many nested properties.
Typescript Type Definition
interface Feature {
id: string;
archived: boolean;
description: string;
owner: string;
project: string;
dateCreated: string;
dateUpdated: string;
valueType: "boolean" | "number" | "string" | "json";
defaultValue: string;
tags: string[];
environments: {
[key: string]: FeatureEnvironment;
};
revision: {
version: number;
comment: string;
date: string;
publishedBy: string;
};
}
interface FeatureEnvironment {
enabled: boolean;
defaultValue: string;
rules: FeatureRule[];
definition: FeatureDefinition | null;
draft: null | {
enabled: boolean;
defaultValue: string;
rules: FeatureRule[];
definition: FeatureDefinition | null;
};
}
type FeatureRule = ForceRule | RolloutRule | ExperimentRule;
interface ForceRule {
type: "force";
description: string;
condition?: string;
id: string;
enabled?: boolean;
value: string;
}
interface RolloutRule {
type: "rollout";
description: string;
condition?: string;
id: string;
enabled?: boolean;
value: string;
coverage: number;
hashAttribute: string;
}
interface ExperimentRule {
type: "experiment";
description: string;
condition?: string;
id: string;
enabled?: boolean;
trackingKey: string;
hashAttribute: string;
namespace?: {
enabled: boolean;
name: string;
range: [number, number];
};
coverage?: number;
values: {
value: string;
weight: number;
name?: string;
}[];
}
// This is the same format returned from the SDK Endpoints
interface FeatureDefinition {
defaultValue: any;
rules?: FeatureDefinitionRule[];
}
interface FeatureDefinitionRule {
force?: any;
weights?: number[];
variations?: any[];
hashAttribute?: string;
namespace?: [string, number, number];
key?: string;
coverage?: number;
condition?: any;
}
Example JSON object
{
"id": "my-test-feature",
"description": "My test feature!!!",
"archived": false,
"dateCreated": "2022-10-18T21:19:58.288Z",
"dateUpdated": "2022-10-18T21:42:29.835Z",
"defaultValue": "false",
"environments": {
"production": {
"defaultValue": "false",
"enabled": true,
"rules": [
{
"type": "force",
"description": "Turn on for admins",
"id": "fr_75x7w5jn14l9eqd7g7",
"value": "true",
"enabled": true,
"condition": "{\"admin\":true}"
}
],
"draft": null,
"definition": {
"defaultValue": false,
"rules": [
{
"condition": {
"admin": true
},
"force": true
}
]
}
}
},
"owner": "John Smith",
"project": "",
"tags": ["cool-features"],
"valueType": "boolean",
"revision": {
"comment": "",
"date": "2022-10-18T21:22:10.379Z",
"publishedBy": "test@example.com",
"version": 2
}
}
List Features
GET /api/v1/features
This endpoint returns all of the features in your account, sorted by dateCreated in chronological order (oldest first).
curl https://api.growthbook.io/api/v1/features \
-u secret_abc123DEF456:
The reponse body contains a list of features and pagination information.
Typescript Type Definition
interface ListFeaturesResponse {
features: Feature[];
// Pagination info
limit: number;
offset: number;
count: number;
total: number;
hasMore: boolean;
nextOffset: number;
}
Example JSON object
{
"features": [
{
"id": "my-test-feature",
"description": "My test feature!!!",
"archived": false,
"dateCreated": "2022-10-18T21:19:58.288Z",
"dateUpdated": "2022-10-18T21:42:29.835Z",
"defaultValue": "false",
"environments": {
"production": {
"defaultValue": "false",
"enabled": true,
"rules": [],
"draft": null,
"definition": {
"defaultValue": false
}
}
},
"owner": "John Smith",
"project": "",
"tags": ["cool-features"],
"valueType": "boolean",
"revision": {
"comment": "",
"date": "2022-10-18T21:22:10.379Z",
"publishedBy": "test@example.com",
"version": 2
}
}
],
"limit": 1,
"offset": 0,
"count": 1,
"total": 20,
"hasMore": true,
"nextOffset": 1
}
Toggle Feature
POST /api/v1/features/:key/toggle
This endpoint controls the environment toggles for features.
curl -X POST https://api.growthbook.io/api/v1/features/my-feature/toggle \
-u secret_abc123DEF456: \
-d "environments[production]"=false \
-d reason="Kill switch activated"
The request body contains the following fields:
- environments - An object mapping environment names to the desired toggle state. Not all environments need to be specified, only those you want to change.
- reason - An optional string explaining why you are making this change (for the audit trail)
Example JSON
{
"environments": {
"dev": true,
"production": false
},
"reason": "Kill switch activated"
}
The reponse body contains the new Feature object after the changes are applied.
Typescript Type Definition
interface ToggleFeaturesResponse {
feature: Feature;
}
Example JSON object
{
"feature": {
"id": "my-test-feature",
"description": "My test feature!!!",
"archived": false,
"dateCreated": "2022-10-18T21:19:58.288Z",
"dateUpdated": "2022-10-18T21:42:29.835Z",
"defaultValue": "false",
"environments": {
"production": {
"defaultValue": "false",
"enabled": false,
"rules": [],
"draft": null,
"definition": {
"defaultValue": false
}
}
}
}
}
SDK Connection Endpoints
SDK Connection Endpoints provide readonly access to a subset of your feature flags, just enough for the GrowthBook SDKs to assign values to users. They are meant to be public and do not require authentication to view.
In GrowthBook Cloud, the SDK Connection Endpoints are served from our global CDN: https://cdn.growthbook.io/api/features/...
. If you are self-hosting, you can run the GrowthBook Proxy server, which provides built-in caching and performance optimizations.
SDK Connection Endpoints are scoped to a single Environment (e.g. dev
or production
) and can also be scoped to a single Project. Manage all of your SDK Connections on the Features -> SDKs page.
Typescript Type Definition
interface SDKEndpointResponse {
status: 200;
features: {
[key: string]: FeatureDefinition
}
}
interface FeatureDefinition {
defaultValue: any;
rules?: FeatureDefinitionRule[];
}
interface FeatureDefinitionRule {
force?: any;
weights?: number[];
variations?: any[];
hashAttribute?: string;
namespace?: [string, number, number];
key?: string;
coverage?: number;
condition?: any;
}
Example JSON object
{
"status": 200,
"features": {
"feature-key": {
"defaultValue": true
},
"another-feature": {
"defaultValue": "blue",
"rules": [
{
"condition": {
"browser": "firefox"
},
"force": "green"
}
]
}
}
}
Encryption
If you've enabled encryption for your SDK endpoint, the response format changes:
Typescript Type Definition
interface SDKEncryptedEndpointResponse {
status: 200;
encryptedFeatures: string;
}
Example JSON object
{
"status": 200,
"encryptedFeatures": "abcdef123456GHIJKL0987654321..."
}
You will need to decrypt the features first before passing into the SDK. Our front-end SDKs (Javascript and React) handle this for you automatically and we're in the process of adding built-in support to our other SDKs.