Skip to main content
GrowthBook offers a full REST API for interacting with the application. 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/api. For self-hosted deployments, it is the same as your API_HOST environment variable (defaults to http://localhost:3100/api). The rest of these docs will assume you are using GrowthBook Cloud.

​
Versioning

Endpoints are versioned by path prefix:
  • /v1/... — stable, widely-supported endpoints
  • /v2/... — updated endpoints with improved shapes (e.g. unified per-rule environment scope for feature flags)
New integrations should prefer v2 where available. Feature-flag and metric v1 routes are deprecated: they are tagged LEGACY in the sidebar and collapsed by default. Use the matching v2 group when both exist.

​
Authentication

We support both the HTTP Basic and Bearer authentication schemes for convenience. You first need to generate a new API Key in GrowthBook. Different keys have different permissions:
  • Personal Access Tokens: These are sensitive and provide the same level of access as the user has to an organization. These can be created by going to Personal Access Tokens under the your user menu.
  • Secret Keys: These are sensitive and provide the level of access for the role, which currently is either admin or readonly. Only Admins with the manageApiKeys permission can manage Secret Keys on behalf of an organization. These can be created by going to Settings -> API Keys
If using HTTP Basic auth, pass the Secret Key as the username and leave the password blank (when using curl, add : at the end of the secret to indicate an empty password)
If using Bearer auth, pass the Secret Key as the token:

​
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
  • 422 - Soft Warning - The request failed, but can be re-submitted with ?ignoreWarnings=true to proceed anyway.
  • 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