Skip to main content

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, 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
}

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.