API

GrowthBook's API has both public endpoints plus an authenticated REST API beta.

Public Endpoints

Currently, GrowthBook has a single public endpoint, the SDK Endpoint. This is a unique URL that returns your feature definitions, which can be passed into any of the GrowthBook SDKs - front-end, server-side, or mobile. View All SDKs

Using this endpoint is one way to get your feature definitions. The other way is via Webhooks, where we send the same payload to you automatically whenever someone updates a feature in GrowthBook.

Environments

SDK Endpoints are scoped to a single environment (e.g. dev or production).

When you first create a GrowthBook account, we add a default "production" environment for you with a single SDK Endpoint. You can add new environments and SDK Endpoints by going to Features -> Environments.

The SDK Endpoint

In GrowthBook Cloud, the SDK endpoint is served from our global CDN: https://cdn.growthbook.io/api/features/.... If you are self-hosting, you'll want to set up either a CDN or cache layer yourself in front of the GrowthBook API for scalability and speed.

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"
        }
      ]
    }
  }
}

Project-scoping

If you've set up multiple projects within GrowthBook, you can optionally add a querystring to the SDK endpoint to only include features in a specific project. By default, features from all projects are returned.

To do this, add the querystring ?project={projectId}. You can find the id for your project under Settings > Projects (will start with prj_).

For example:

/api/features/dev_abc123?project=prj_456def

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. You can find your encryption key on the Features -> Environments page in GrowthBook.

Here's an example in JavaScript using the SubtleCrypto API, which is available in all modern web browsers:

Decryption Code Example

async function decrypt(encryptedText) {
  const GB_ENCRYPTION_KEY = "MY_ENCRYPTION_KEY"; // <-- Set your encryption key here
  const base64ToBuf = (b) => Uint8Array.from(atob(b), (c) => c.charCodeAt(0));
  const key = await window.crypto.subtle.importKey(
    "raw", base64ToBuf(GB_ENCRYPTION_KEY),
    { name: "AES-CBC", length: 128 }, true, ["encrypt", "decrypt"]
  );
  const [iv, cipherText] = encryptedText.split(".");
  const plainTextBuffer = await window.crypto.subtle
    .decrypt({name: "AES-CBC", iv: base64ToBuf(iv)}, key, base64ToBuf(cipherText));
  return new TextDecoder().decode(plainTextBuffer);
}

// Decrypting gives you a JSON-encoded string
const featuresStr = await decrypt(encryptedFeatures);

// Turn it into a JSON object
const features = JSON.parse(featuresStr);

Authenticated REST API beta

In addition to the public API endpoints, GrowthBook also 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.

All request and 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, default 10
offset - how many to skip, default 0

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 request
offset - The offset used for the current request
count - Number returned in the response
total - Total number of items
hasMore - true if there is another page, false if there are no more items
nextOffset - Offset to fetch the next page, or null 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
}