GrowthBook REST API

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