Docs Home
How it works
Self-Host
Environment Variables
Config.yml
Platform
Data Sources
Metrics
Features
Experiments
Dimensions
Visual Editorbeta
API
Webhooks
How to
Next.js
Create React App
Google Analytics - UA
Mixpanel
Matomo
BigQuery
Rudderstack
Rudderstack + Next.js
SDKs
Javascript
React
PHP
Ruby
Python
Go
Kotlin (Android)
Flutter
Build Your Own
Integrations
Vercel
FAQ
Statistics

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.

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.

Here is an example response from an SDK endpoint (pretty-printed for readability):

{
  "status": 200,
  "features": {
    "feature-key": {
      "defaultValue": true
    },
    "another-feature": {
      "defaultValue": "blue",
      "rules": [
        {
          "condition": {
            "browser": "firefox"
          },
          "force": "green"
        }
      ]
    }
  }
}

The status field mirrors the HTTP status. The features field has feature definitions indexed by the feature key.

Each feature definition has a default value and optional rules that override the value based on targeting conditions. Rules can also be experiments or rollouts where values are randomly assigned to users.

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

Official SDKs

We offer official SDKs that work with these data structures in a few popular languages with more coming soon.

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
}