GrowthBook REST API
GrowthBook REST API for managing projects, environments, feature flags, feature revisions, experiments, snapshots, metrics, fact tables, dimensions, segments, saved groups, teams, members, organizations, and dashboards.
OpenAPI Specification
openapi: 3.1.0
info:
version: 1.0.0
title: GrowthBook REST API
description: >
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.
## 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)
```bash
curl https://api.growthbook.io/api/v1/features \
-u secret_abc123DEF456:
```
If using Bearer auth, pass the Secret Key as the token:
```bash
curl https://api.growthbook.io/api/v1/features \
-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
servers:
- url: https://api.growthbook.io/api
description: GrowthBook Cloud
- url: https://{domain}/api
description: Self-hosted GrowthBook
tags:
- name: projects
x-displayName: Projects
description: Projects are used to organize your feature flags and experiments
- name: environments
x-displayName: Environments
description: >-
GrowthBook comes with one environment by default (production), but you can
add as many as you need. When used with feature flags, you can
enable/disable feature flags on a per-environment basis.
- name: features-v2
x-displayName: Feature Flags
description: >-
Control your feature flags programatically.
Rules are returned as a unified top-level array; each rule carries
`allEnvironments` / `environments` scope fields instead of being bucketed
by environment.
- name: feature-revisions-v2
x-displayName: Feature Revisions
description: >-
Draft revisions for feature flags, including rules, scheduling, and
approval workflows.
Revision `rules` is a flat array with per-rule scope fields.
- name: features
x-displayName: Feature Flags (legacy)
description: >-
Control your feature flags programatically.
**These are v1 endpoints.** New integrations should use the v2 Feature
Flags endpoints, which expose a unified per-rule environment scope instead
of per-environment rule arrays.
- name: feature-revisions
x-displayName: Feature Revisions (legacy)
description: >-
Draft revisions for feature flags, including rules, scheduling, and
approval workflows.
**These are v1 endpoints.** New integrations should use the v2 Feature
Revisions endpoints.
- name: ramp-schedules
x-displayName: Ramp Schedules
description: >-
Multi-step rollout schedules that gradually ramp feature rule changes over
time, with support for interval, approval, and scheduled triggers.
- name: data-sources
x-displayName: Data Sources
description: >-
How GrowthBook connects and queries your data, including cached database
schema metadata (information schemas) for tables and columns.
- name: fact-tables
x-displayName: Fact Tables
description: Fact Tables describe the shape of your data warehouse tables
- name: fact-metrics
x-displayName: Fact Metrics
description: Fact Metrics are metrics built on top of Fact Table definitions
- name: metrics
x-displayName: Metrics (legacy)
description: Metrics used as goals and guardrails for experiments
- name: experiments
x-displayName: Experiments
description: Experiments (A/B Tests)
- name: namespaces
x-displayName: Namespaces
description: >-
Namespaces partition your user population into buckets so that experiments
using the same hash attribute do not overlap unintentionally. Each
namespace defines a 0–1 range and individual experiments claim sub-ranges
within it.
- name: snapshots
x-displayName: Experiment Snapshots
description: Experiment Snapshots (the individual updates of an experiment)
- name: dimensions
x-displayName: Dimensions
description: Dimensions used during experiment analysis
- name: segments
x-displayName: Segments
description: Segments used during experiment analysis
- name: sdk-connections
x-displayName: SDK Connections
description: Client keys and settings for connecting SDKs to a GrowthBook instance
- name: visual-changesets
x-displayName: Visual Changesets
description: Groups of visual changes made by the visual editor to a single page
- name: saved-groups
x-displayName: Saved Groups
description: >-
Defined sets of attribute values which can be used with feature rules for
targeting features at particular users.
- name: organizations
x-displayName: Organizations
description: >-
Organizations are used for multi-org deployments where different teams can
run their own isolated feature flags and experiments. These endpoints are
only via a super-admin's Personal Access Token.
- name: members
x-displayName: Members
description: Members are users who have been invited to an organization.
- name: code-references
x-displayName: Code References
description: >-
Intended for use with our code reference CI utility,
[`gb-find-code-refs`](https://github.com/growthbook/gb-find-code-refs).
- name: archetypes
x-displayName: Archetypes
description: >-
Archetypes allow you to simulate the result of targeting rules on pre-set
user attributes
- name: queries
x-displayName: Queries
description: Retrieve queries used in experiments to calculate results.
- name: settings
x-displayName: Settings
description: Get the organization settings.
- name: attributes
x-displayName: Attributes
description: Used when targeting feature flags and experiments.
- name: usage
x-displayName: Usage
description: Usage information for metrics in experiments.
- name: Dashboards
x-displayName: Dashboards
description: ''
- name: CustomFields
x-displayName: Custom Fields
description: ''
- name: MetricGroups
x-displayName: Metric Groups
description: ''
- name: Teams
x-displayName: Teams
description: ''
- name: ExperimentTemplates
x-displayName: Experiment Templates
description: ''
- name: AnalyticsExplorations
x-displayName: Analytics Explorations
description: ''
- name: RampScheduleTemplates
x-displayName: Ramp Schedule Templates
description: Reusable step configurations for ramp schedules.
- name: AnalyticsExploration_model
x-displayName: AnalyticsExploration
description: <SchemaDefinition schemaRef="#/components/schemas/AnalyticsExploration" />
- name: Archetype_model
x-displayName: Archetype
description: <SchemaDefinition schemaRef="#/components/schemas/Archetype" />
- name: Attribute_model
x-displayName: Attribute
description: <SchemaDefinition schemaRef="#/components/schemas/Attribute" />
- name: CodeRef_model
x-displayName: CodeRef
description: <SchemaDefinition schemaRef="#/components/schemas/CodeRef" />
- name: CustomField_model
x-displayName: CustomField
description: <SchemaDefinition schemaRef="#/components/schemas/CustomField" />
- name: Dashboard_model
x-displayName: Dashboard
description: <SchemaDefinition schemaRef="#/components/schemas/Dashboard" />
- name: DataSource_model
x-displayName: DataSource
description: <SchemaDefinition schemaRef="#/components/schemas/DataSource" />
- name: Dimension_model
x-displayName: Dimension
description: <SchemaDefinition schemaRef="#/components/schemas/Dimension" />
- name: Environment_model
x-displayName: Environment
description: <SchemaDefinition schemaRef="#/components/schemas/Environment" />
- name: Experiment_model
x-displayName: Experiment
description: <SchemaDefinition schemaRef="#/components/schemas/Experiment" />
- name: ExperimentAnalysisSettings_model
x-displayName: ExperimentAnalysisSettings
description: >-
<SchemaDefinition
schemaRef="#/components/schemas/ExperimentAnalysisSettings" />
- name: ExperimentDecisionFrameworkSettings_model
x-displayName: ExperimentDecisionFrameworkSettings
description: >-
<SchemaDefinition
schemaRef="#/components/schemas/ExperimentDecisionFrameworkSettings" />
- name: ExperimentMetric_model
x-displayName: ExperimentMetric
description: <SchemaDefinition schemaRef="#/components/schemas/ExperimentMetric" />
- name: ExperimentMetricOverrideEntry_model
x-displayName: ExperimentMetricOverrideEntry
description: >-
<SchemaDefinition
schemaRef="#/components/schemas/ExperimentMetricOverrideEntry" />
- name: ExperimentResults_model
x-displayName: ExperimentResults
description: <SchemaDefinition schemaRef="#/components/schemas/ExperimentResults" />
- name: ExperimentSnapshot_model
x-displayName: ExperimentSnapshot
description: <SchemaDefinition schemaRef="#/components/schemas/ExperimentSnapshot" />
- name: ExperimentTemplate_model
x-displayName: ExperimentTemplate
description: <SchemaDefinition schemaRef="#/components/schemas/ExperimentTemplate" />
- name: ExperimentWithEnhancedStatus_model
x-displayName: ExperimentWithEnhancedStatus
description: >-
<SchemaDefinition
schemaRef="#/components/schemas/ExperimentWithEnhancedStatus" />
- name: FactMetric_model
x-displayName: FactMetric
description: <SchemaDefinition schemaRef="#/components/schemas/FactMetric" />
- name: FactTable_model
x-displayName: FactTable
description: <SchemaDefinition schemaRef="#/components/schemas/FactTable" />
- name: FactTableColumn_model
x-displayName: FactTableColumn
description: <SchemaDefinition schemaRef="#/components/schemas/FactTableColumn" />
- name: FactTableFilter_model
x-displayName: FactTableFilter
description: <SchemaDefinition schemaRef="#/components/schemas/FactTableFilter" />
- name: Feature_model
x-displayName: Feature
description: <SchemaDefinition schemaRef="#/components/schemas/Feature" />
- name: FeatureBaseRule_model
x-displayName: FeatureBaseRule
description: <SchemaDefinition schemaRef="#/components/schemas/FeatureBaseRule" />
- name: FeatureDefinition_model
x-displayName: FeatureDefinition
description: <SchemaDefinition schemaRef="#/components/schemas/FeatureDefinition" />
- name: FeatureEnvironment_model
x-displayName: FeatureEnvironment
description: <SchemaDefinition schemaRef="#/components/schemas/FeatureEnvironment" />
- name: FeatureEnvironmentV2_model
x-displayName: FeatureEnvironmentV2
description: <SchemaDefinition schemaRef="#/components/schemas/FeatureEnvironmentV2" />
- name: FeatureExperimentRefRule_model
x-displayName: FeatureExperimentRefRule
description: >-
<SchemaDefinition
schemaRef="#/components/schemas/FeatureExperimentRefRule" />
- name: FeatureExperimentRule_model
x-displayName: FeatureExperimentRule
description: >-
<SchemaDefinition schemaRef="#/components/schemas/FeatureExperimentRule"
/>
- name: FeatureForceRule_model
x-displayName: FeatureForceRule
description: <SchemaDefinition schemaRef="#/components/schemas/FeatureForceRule" />
- name: FeatureRevision_model
x-displayName: FeatureRevision
description: <SchemaDefinition schemaRef="#/components/schemas/FeatureRevision" />
- name: FeatureRevisionV2_model
x-displayName: FeatureRevisionV2
description: <SchemaDefinition schemaRef="#/components/schemas/FeatureRevisionV2" />
- name: FeatureRolloutRule_model
x-displayName: FeatureRolloutRule
description: <SchemaDefinition schemaRef="#/components/schemas/FeatureRolloutRule" />
- name: FeatureRule_model
x-displayName: FeatureRule
description: <SchemaDefinition schemaRef="#/components/schemas/FeatureRule" />
- name: FeatureRuleV2_model
x-displayName: FeatureRuleV2
description: <SchemaDefinition schemaRef="#/components/schemas/FeatureRuleV2" />
- name: FeatureSafeRolloutRule_model
x-displayName: FeatureSafeRolloutRule
description: >-
<SchemaDefinition schemaRef="#/components/schemas/FeatureSafeRolloutRule"
/>
- name: FeatureV2_model
x-displayName: FeatureV2
description: <SchemaDefinition schemaRef="#/components/schemas/FeatureV2" />
- name: FeatureWithRevisions_model
x-displayName: FeatureWithRevisions
description: <SchemaDefinition schemaRef="#/components/schemas/FeatureWithRevisions" />
- name: FeatureWithRevisionsV2_model
x-displayName: FeatureWithRevisionsV2
description: >-
<SchemaDefinition schemaRef="#/components/schemas/FeatureWithRevisionsV2"
/>
- name: InformationSchema_model
x-displayName: InformationSchema
description: <SchemaDefinition schemaRef="#/components/schemas/InformationSchema" />
- name: InformationSchemaTable_model
x-displayName: InformationSchemaTable
description: >-
<SchemaDefinition schemaRef="#/components/schemas/InformationSchemaTable"
/>
- name: LookbackOverride_model
x-displayName: LookbackOverride
description: <SchemaDefinition schemaRef="#/components/schemas/LookbackOverride" />
- name: Member_model
x-displayName: Member
description: <SchemaDefinition schemaRef="#/components/schemas/Member" />
- name: Metric_model
x-displayName: Metric
description: <SchemaDefinition schemaRef="#/components/schemas/Metric" />
- name: MetricAnalysis_model
x-displayName: MetricAnalysis
description: <SchemaDefinition schemaRef="#/components/schemas/MetricAnalysis" />
- name: MetricGroup_model
x-displayName: MetricGroup
description: <SchemaDefinition schemaRef="#/components/schemas/MetricGroup" />
- name: MetricUsage_model
x-displayName: MetricUsage
description: <SchemaDefinition schemaRef="#/components/schemas/MetricUsage" />
- name: Namespace_model
x-displayName: Namespace
description: <SchemaDefinition schemaRef="#/components/schemas/Namespace" />
- name: NamespaceExperimentMember_model
x-displayName: NamespaceExperimentMember
description: >-
<SchemaDefinition
schemaRef="#/components/schemas/NamespaceExperimentMember" />
- name: Organization_model
x-displayName: Organization
description: <SchemaDefinition schemaRef="#/components/schemas/Organization" />
- name: PaginationFields_model
x-displayName: PaginationFields
description: <SchemaDefinition schemaRef="#/components/schemas/PaginationFields" />
- name: Project_model
x-displayName: Project
description: <SchemaDefinition schemaRef="#/components/schemas/Project" />
- name: Query_model
x-displayName: Query
description: <SchemaDefinition schemaRef="#/components/schemas/Query" />
- name: RampSchedule_model
x-displayName: RampSchedule
description: <SchemaDefinition schemaRef="#/components/schemas/RampSchedule" />
- name: RampScheduleTemplate_model
x-displayName: RampScheduleTemplate
description: <SchemaDefinition schemaRef="#/components/schemas/RampScheduleTemplate" />
- name: SavedGroup_model
x-displayName: SavedGroup
description: <SchemaDefinition schemaRef="#/components/schemas/SavedGroup" />
- name: ScheduleRule_model
x-displayName: ScheduleRule
description: <SchemaDefinition schemaRef="#/components/schemas/ScheduleRule" />
- name: SdkConnection_model
x-displayName: SdkConnection
description: <SchemaDefinition schemaRef="#/components/schemas/SdkConnection" />
- name: Segment_model
x-displayName: Segment
description: <SchemaDefinition schemaRef="#/components/schemas/Segment" />
- name: Settings_model
x-displayName: Settings
description: <SchemaDefinition schemaRef="#/components/schemas/Settings" />
- name: Team_model
x-displayName: Team
description: <SchemaDefinition schemaRef="#/components/schemas/Team" />
- name: VisualChange_model
x-displayName: VisualChange
description: <SchemaDefinition schemaRef="#/components/schemas/VisualChange" />
- name: VisualChangeset_model
x-displayName: VisualChangeset
description: <SchemaDefinition schemaRef="#/components/schemas/VisualChangeset" />
security:
- bearerAuth: []
- basicAuth: []
paths:
/v1/features:
get:
operationId: listFeatures
summary: Get all features
description: >
**Deprecated.** Use [GET /v2/features](#operation/listFeaturesV2)
instead.
Returns features with pagination. The skipPagination query parameter is
honored only when API_ALLOW_SKIP_PAGINATION is set (self-hosted
deployments).
deprecated: true
tags:
- features
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/projectId'
- $ref: '#/components/parameters/clientKey'
- $ref: '#/components/parameters/skipPagination'
responses:
'200':
content:
application/json:
schema:
allOf:
- type: object
properties:
features:
type: array
items:
$ref: '#/components/schemas/Feature'
required:
- features
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/features' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postFeature
summary: Create a single feature
description: >-
**Deprecated.** Use [POST /v2/features](#operation/postFeatureV2)
instead.
deprecated: true
tags:
- features
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
description: >-
A unique key name for the feature. Feature keys can only
include letters, numbers, hyphens, and underscores.
type: string
minLength: 1
archived:
type: boolean
description:
description: Description of the feature
type: string
owner:
description: >-
The userId or email address of the owner. If an email
address is provided, it will be used to look up the userId
of the matching organization member. If an ID is provided,
it will be validated as existing in the organization.
type: string
project:
description: An associated project ID
type: string
valueType:
description: The data type of the feature payload. Boolean by default.
type: string
enum:
- boolean
- string
- number
- json
defaultValue:
description: >-
Default value when feature is enabled. Type must match
`valueType`.
type: string
tags:
description: List of associated tags
type: array
items:
type: string
environments:
description: >-
A dictionary of environments that are enabled for this
feature. Keys supply the names of environments. Environments
belong to organization and are not specified will be
disabled by default.
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
enabled:
type: boolean
rules:
type: array
items:
anyOf:
- type: object
properties:
description:
type: string
condition:
description: Applied to everyone by default.
type: string
savedGroupTargeting:
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: force
value:
type: string
required:
- type
- value
additionalProperties: false
- type: object
properties:
description:
type: string
condition:
description: Applied to everyone by default.
type: string
savedGroupTargeting:
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: rollout
value:
type: string
coverage:
description: >-
Percent of traffic included in this
experiment. Users not included in the
experiment will skip this rule.
type: number
hashAttribute:
type: string
required:
- type
- value
- coverage
- hashAttribute
additionalProperties: false
- type: object
properties:
description:
type: string
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: experiment-ref
condition:
type: string
savedGroupTargeting:
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
variations:
type: array
items:
type: object
properties:
value:
type: string
variationId:
type: string
required:
- value
- variationId
additionalProperties: false
experimentId:
type: string
required:
- type
- variations
- experimentId
additionalProperties: false
- type: object
properties:
description:
type: string
condition:
type: string
id:
type: string
enabled:
description: Enabled by default
# --- truncated at 32 KB (1210 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/growthbook/refs/heads/main/openapi/growthbook-openapi.yaml