> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.growthbook.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Partially update a feature
> Updates any combination of a feature's metadata, default value, environment state, and rules. Other top-level fields are patch-merged: omit a field to leave it unchanged. The `rules` field, when supplied, replaces the entire `rules` array atomically in a single revision (v1 PUT applied per-environment patches; v2 swaps the full flat array). To preserve existing rules during a partial edit, GET the feature first, mutate the returned `rules` array, and PUT the full array back. Safe-rollout rules round-trip via their `safeRolloutId`; use `POST /v2/features/:id/revisions/:version/rules` to create new ones. Returns 403 if approval rules are enabled for an affected environment and the bypass setting is off.
## OpenAPI
````yaml openapi.yaml POST /v2/features/{id}
openapi: 3.1.0
info:
version: 4.4.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
- **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
servers:
- url: https://api.growthbook.io/api
description: GrowthBook Cloud
- url: https://{domain}/api
description: Self-hosted GrowthBook
variables:
domain:
default: localhost:3100
description: Your self-hosted GrowthBook host (and port)
security:
- bearerAuth: []
- basicAuth: []
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 increase feature rule traffic
over time, with optional real-time monitoring. Each step supports interval
timers, approval gates, and hold conditions. Monitored steps are backed by
a live analysis experiment that can automatically hold, roll back, or
advance the ramp based on guardrail and signal metric health.
- 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: reports
x-displayName: Experiment Reports
description: >-
Custom analysis reports built on top of experiment snapshots. Reports let
you re-run analysis with different metrics, date ranges, stats engines,
and other settings without modifying the underlying experiment.
- 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: saved-group-revisions
x-displayName: Saved Group Revisions
description: >-
Draft revisions for saved groups, including pending changes, approvals,
and lifecycle (publish, discard, revert).
Most callers can interact with these endpoints via shorthand actions
(`/items/add`, `/items/remove`, single-field PUTs) instead of authoring
JSON Patch ops directly. Pass `version: "new"` on edit endpoints to
auto-create a draft.
- name: releases
x-displayName: Releases
description: >-
**Beta** — these endpoints are new and may change in
backwards-incompatible ways.
Coordinated multi-entity publishing: publish a set of revisions across
Feature Flags, Saved Groups, configs, and constants as one all-or-nothing
operation, validated against the combined end-state instead of each
in-between state. Requires the `releases` commercial feature.
- 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: meta
x-displayName: Meta
description: >-
Server metadata, including the running build's version and commit for
version-skew checks.
- 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: AggregatedFactTable_model
x-displayName: Aggregated Fact Table
description:
- name: AnalyticsExploration_model
x-displayName: Analytics Exploration
description:
- name: Archetype_model
x-displayName: Archetype
description:
- name: Attribute_model
x-displayName: Attribute
description:
- name: CodeRef_model
x-displayName: Code Ref
description:
- name: CustomField_model
x-displayName: Custom Field
description:
- name: Dashboard_model
x-displayName: Dashboard
description:
- name: DataSource_model
x-displayName: Data Source
description:
- name: Dimension_model
x-displayName: Dimension
description:
- name: Environment_model
x-displayName: Environment
description:
- name: EventUser_model
x-displayName: Event User
description:
- name: Experiment_model
x-displayName: Experiment
description:
- name: Experiment Rule_model
x-displayName: Experiment Rule
description:
- name: ExperimentAnalysisSettings_model
x-displayName: Experiment Analysis Settings
description: >-
- name: ExperimentDecisionFrameworkSettings_model
x-displayName: Experiment Decision Framework Settings
description: >-
- name: ExperimentMetric_model
x-displayName: Experiment Metric
description:
- name: ExperimentMetricOverrideEntry_model
x-displayName: Experiment Metric Override Entry
description: >-
- name: ExperimentResults_model
x-displayName: Experiment Results
description:
- name: ExperimentSnapshot_model
x-displayName: Experiment Snapshot
description:
- name: ExperimentTemplate_model
x-displayName: Experiment Template
description:
- name: ExperimentWithEnhancedStatus_model
x-displayName: Experiment With Enhanced Status
description: >-
- name: FactMetric_model
x-displayName: Fact Metric
description:
- name: FactTable_model
x-displayName: Fact Table
description:
- name: FactTableColumn_model
x-displayName: Fact Table Column
description:
- name: FactTableFilter_model
x-displayName: Fact Table Filter
description:
- name: FeatureBaseRule_model
x-displayName: Feature Base Rule
description:
- name: FeatureDefinition_model
x-displayName: Feature Definition
description:
- name: FeatureEnvironmentV1_model
x-displayName: Feature Environment V1
description:
- name: FeatureEnvironmentV2_model
x-displayName: Feature Environment V2
description:
- name: FeatureExperimentRefRule_model
x-displayName: Feature Experiment Ref Rule
description: >-
- name: FeatureExperimentRule_model
x-displayName: Feature Experiment Rule
description: >-
- name: FeatureForceRule_model
x-displayName: Feature Force Rule
description:
- name: FeatureRevisionSummary_model
x-displayName: Feature Revision Summary
description: >-
- name: FeatureRevisionV1_model
x-displayName: Feature Revision V1
description:
- name: FeatureRevisionV2_model
x-displayName: Feature Revision V2
description:
- name: FeatureRolloutRule_model
x-displayName: Feature Rollout Rule
description:
- name: FeatureRuleV1_model
x-displayName: Feature Rule V1
description:
- name: FeatureRuleV2_model
x-displayName: Feature Rule V2
description:
- name: FeatureSafeRolloutRule_model
x-displayName: Feature Safe Rollout Rule
description: >-
- name: FeatureV1_model
x-displayName: Feature V1
description:
- name: FeatureV2_model
x-displayName: Feature V2
description:
- name: FeatureWithRevisionsV1_model
x-displayName: Feature With Revisions V1
description: >-
- name: FeatureWithRevisionsV2_model
x-displayName: Feature With Revisions V2
description: >-
- name: InformationSchema_model
x-displayName: Information Schema
description:
- name: InformationSchemaTable_model
x-displayName: Information Schema Table
description: >-
- name: LookbackOverride_model
x-displayName: Lookback Override
description:
- name: Member_model
x-displayName: Member
description:
- name: Metric_model
x-displayName: Metric
description:
- name: MetricAnalysis_model
x-displayName: Metric Analysis
description:
- name: MetricGroup_model
x-displayName: Metric Group
description:
- name: MetricUsage_model
x-displayName: Metric Usage
description:
- name: Namespace_model
x-displayName: Namespace
description:
- name: NamespaceExperimentMember_model
x-displayName: Namespace Experiment Member
description: >-
- name: Organization_model
x-displayName: Organization
description:
- name: PaginationFields_model
x-displayName: Pagination Fields
description:
- name: Project_model
x-displayName: Project
description:
- name: Query_model
x-displayName: Query
description:
- name: RampSchedule_model
x-displayName: Ramp Schedule
description:
- name: RampScheduleTemplate_model
x-displayName: Ramp Schedule Template
description:
- name: Report_model
x-displayName: Report
description:
- name: Safe Rollout Rule_model
x-displayName: Safe Rollout Rule
description:
- name: SavedGroup_model
x-displayName: Saved Group
description:
- name: SavedGroupRevision_model
x-displayName: Saved Group Revision
description:
- name: SavedGroupRevisionActivityLogEntry_model
x-displayName: Saved Group Revision Activity Log Entry
description: >-
- name: SavedGroupRevisionReview_model
x-displayName: Saved Group Revision Review
description: >-
- name: ScheduleRule_model
x-displayName: Schedule Rule
description:
- name: SdkConnection_model
x-displayName: Sdk Connection
description:
- name: Segment_model
x-displayName: Segment
description:
- name: Settings_model
x-displayName: Settings
description:
- name: Targeting Rule_model
x-displayName: Targeting Rule
description:
- name: Team_model
x-displayName: Team
description:
- name: VisualChange_model
x-displayName: Visual Change
description:
- name: VisualChangeset_model
x-displayName: Visual Changeset
description:
paths:
/v2/features/{id}:
post:
tags:
- features-v2
summary: Partially update a feature
description: >-
Updates any combination of a feature's metadata, default value,
environment state, and rules. Other top-level fields are patch-merged:
omit a field to leave it unchanged. The `rules` field, when supplied,
replaces the entire `rules` array atomically in a single revision (v1
PUT applied per-environment patches; v2 swaps the full flat array). To
preserve existing rules during a partial edit, GET the feature first,
mutate the returned `rules` array, and PUT the full array back.
Safe-rollout rules round-trip via their `safeRolloutId`; use `POST
/v2/features/:id/revisions/:version/rules` to create new ones. Returns
403 if approval rules are enabled for an affected environment and the
bypass setting is off.
operationId: updateFeatureV2
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
description:
description: Description of the feature
type: string
maxLength: 10000
archived:
type: boolean
project:
description: An associated project ID
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
defaultValue:
type: string
tags:
description: >-
List of associated tags. Will override tags completely with
submitted list
type: array
items:
type: string
rules:
description: >-
Replaces all feature rules atomically. Behavior differs from
v1: v1 PUT applies per-environment patches, v2 PUT swaps the
entire `rules` array in one revision. To preserve existing
rules during a partial edit, GET the feature first, mutate
the returned `rules` array, and PUT the full array back.
Safe-rollout rules round-trip via their `safeRolloutId`
(creation requires `POST
/v2/features/:id/revisions/:version/rules`).
type: array
items:
anyOf:
- type: object
properties:
description:
type: string
maxLength: 10000
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:
type: object
properties:
timestamp:
description: >-
ISO 8601 date-time, e.g.
"2025-06-01T00:00:00Z".
anyOf:
- format: date-time
type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
id:
type: string
enabled:
type: boolean
type:
type: string
const: force
value:
type: string
sparse:
description: >-
JSON features only. When true, the rule value is a
partial object merged onto the feature's default
value instead of replacing it.
type: boolean
allEnvironments:
description: >-
When true the rule applies to all environments
(default).
type: boolean
environments:
description: >-
Specific environment IDs this rule applies to.
Required when allEnvironments is false.
type: array
items:
type: string
required:
- type
- value
additionalProperties: false
- type: object
properties:
description:
type: string
maxLength: 10000
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:
type: object
properties:
timestamp:
description: >-
ISO 8601 date-time, e.g.
"2025-06-01T00:00:00Z".
anyOf:
- format: date-time
type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
id:
type: string
enabled:
type: boolean
type:
type: string
const: rollout
value:
type: string
sparse:
description: >-
JSON features only. When true, the rule value is a
partial object merged onto the feature's default
value instead of replacing it.
type: boolean
coverage:
type: number
hashAttribute:
type: string
hashVersion:
anyOf:
- type: number
const: 1
- type: number
const: 2
allEnvironments:
description: >-
When true the rule applies to all environments
(default).
type: boolean
environments:
description: >-
Specific environment IDs this rule applies to.
Required when allEnvironments is false.
type: array
items:
type: string
required:
- type
- value
- coverage
- hashAttribute
additionalProperties: false
- type: object
properties:
description:
type: string
maxLength: 10000
id:
type: string
enabled:
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:
type: object
properties:
timestamp:
description: >-
ISO 8601 date-time, e.g.
"2025-06-01T00:00:00Z".
anyOf:
- format: date-time
type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
variations:
type: array
items:
type: object
properties:
value:
type: string
variationId:
type: string
required:
- value
- variationId
additionalProperties: false
experimentId:
type: string
sparse:
description: >-
JSON features only. When true, the rule value is a
partial object merged onto the feature's default
value instead of replacing it.
type: boolean
allEnvironments:
description: >-
When true the rule applies to all environments
(default).
type: boolean
environments:
description: >-
Specific environment IDs this rule applies to.
Required when allEnvironments is false.
type: array
items:
type: string
required:
- type
- variations
- experimentId
additionalProperties: false
- type: object
properties:
description:
type: string
maxLength: 10000
id:
type: string
enabled:
type: boolean
type:
type: string
const: safe-rollout
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:
type: object
properties:
timestamp:
description: >-
ISO 8601 date-time, e.g.
"2025-06-01T00:00:00Z".
anyOf:
- format: date-time
type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
controlValue:
type: string
variationValue:
type: string
hashAttribute:
type: string
trackingKey:
type: string
seed:
type: string
safeRolloutId:
description: >-
ID of an existing SafeRollout on this feature.
Bulk POST/PUT cannot create new safe-rollouts; use
POST /v2/features/:id/revisions/:version/rules to
create one.
type: string
status:
type: string
enum:
- running
- released
- rolled-back
- stopped
allEnvironments:
description: >-
When true the rule applies to all environments
(default).
type: boolean
environments:
description: >-
Specific environment IDs this rule applies to.
Required when allEnvironments is false.
type: array
items:
type: string
required:
- type
- controlValue
- variationValue
- hashAttribute
- safeRolloutId
additionalProperties: false
environments:
description: >-
Per-environment enabled state. V2 rules are specified on the
top-level `rules` field.
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
enabled:
type: boolean
additionalProperties: false
prerequisites:
description: Feature IDs. Each feature must evaluate to `true`
type: array
items:
type: string
jsonSchema:
description: >-
Use JSON schema to validate the payload of a JSON-type
feature value (enterprise only).
type: string
customFields:
type: object
propertyNames:
type: string
additionalProperties:
type: string
holdout:
description: >
Holdout to assign this feature to. Pass `null` to remove the
feature from its current holdout. Omit the field entirely to
leave the holdout unchanged.
anyOf:
- type: object
properties:
id:
description: Holdout ID
type: string
value:
description: >-
The feature value assigned to users in the holdout
treatment group
type: string
required:
- id
- value
additionalProperties: false
- type: 'null'
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
feature:
$ref: '#/components/schemas/FeatureV2'
required:
- feature
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v2/features/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
components:
parameters:
id:
name: id
in: path
required: true
description: The id of the requested resource
schema:
description: The id of the requested resource
type: string
schemas:
FeatureV2:
type: object
properties:
id:
type: string
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
archived:
type: boolean
description:
type: string
maxLength: 10000
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:
type: string
valueType:
type: string
enum:
- boolean
- string
- number
- json
defaultValue:
type: string
tags:
type: array
items:
type: string
rules:
description: >-
Unified rules array. Each rule carries its own environment scope via
`allEnvironments` / `environments`.
type: array
items:
$ref: '#/components/schemas/FeatureRuleV2'
environments:
description: >-
Per-environment enabled state and SDK payload. Rules are on the
top-level `rules` field.
type: object
propertyNames:
type: string
additionalProperties:
$ref: '#/components/schemas/FeatureEnvironmentV2'
prerequisites:
description: Feature IDs. Each feature must evaluate to `true`
type: array
items:
type: string
revision:
$ref: '#/components/schemas/FeatureRevisionSummary'
customFields:
type: object
propertyNames:
type: string
additionalProperties: {}
holdout:
anyOf:
- type: object
properties:
id:
description: Holdout ID
type: string
value:
description: >-
The feature value assigned to users in the holdout treatment
group
type: string
required:
- id
- value
additionalProperties: false
- type: 'null'
required:
- id
- dateCreated
- dateUpdated
- archived
- description
- owner
- project
- valueType
- defaultValue
- tags
- rules
- environments
- revision
additionalProperties: false
FeatureRuleV2:
allOf:
- $ref: '#/components/schemas/FeatureRuleV1'
- type: object
properties:
allEnvironments:
description: >-
When true the rule applies to all environments. When false only
the environments listed in `environments` receive the rule.
type: boolean
environments:
description: >-
The environment IDs this rule is active in. Populated when
`allEnvironments` is false.
type: array
items:
type: string
pendingRamp:
description: >-
Present on draft revisions only. "create" means a ramp schedule
will be created for this rule on publish. "detach" means an
existing live ramp schedule will be removed on publish. Use
PUT/DELETE .../rules/{ruleId}/ramp-schedule to modify.
type: string
enum:
- create
- detach
required:
- allEnvironments
additionalProperties: false
FeatureEnvironmentV2:
type: object
properties:
enabled:
type: boolean
defaultValue:
type: string
definition:
description: A JSON stringified [FeatureDefinition](#tag/FeatureDefinition_model)
type: string
required:
- enabled
- defaultValue
additionalProperties: false
FeatureRevisionSummary:
type: object
properties:
version:
type: integer
comment:
type: string
date:
format: date-time
type: string
createdBy:
$ref: '#/components/schemas/EventUser'
publishedBy:
$ref: '#/components/schemas/EventUser'
required:
- version
- comment
- date
additionalProperties: false
FeatureRuleV1:
anyOf:
- $ref: '#/components/schemas/FeatureForceRule'
- $ref: '#/components/schemas/FeatureRolloutRule'
- $ref: '#/components/schemas/FeatureExperimentRule'
- $ref: '#/components/schemas/FeatureExperimentRefRule'
- $ref: '#/components/schemas/FeatureSafeRolloutRule'
EventUser:
description: The user (or automated actor) responsible for an action
type: object
properties:
type:
type: string
enum:
- dashboard
- api_key
- system
id:
type: string
name:
type: string
email:
type: string
required:
- type
additionalProperties: false
FeatureForceRule:
allOf:
- description: >
Common fields shared by all feature rule types. Specific rule types
extend
this base with their own required properties (value, coverage,
etc.).
type: object
properties:
description:
type: string
maxLength: 10000
condition:
type: string
id:
type: string
enabled:
type: boolean
scheduleRules:
description: Simple time-based on/off schedule for this rule
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
scheduleType:
description: >
UI hint for which scheduling mode is active:
- `none` – no schedule
- `schedule` – simple time-based enable/disable via
`scheduleRules`
- `ramp` – multi-step ramp-up controlled by an associated
RampSchedule document
type: string
enum:
- none
- schedule
- ramp
rampScheduleId:
description: >-
ID of the active RampSchedule document controlling this rule.
Present when `scheduleType` is `ramp` and a live schedule
exists.
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 of the prerequisite
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
required:
- description
- id
- enabled
additionalProperties: false
- type: object
properties:
type:
type: string
const: force
value:
type: string
sparse:
description: >-
JSON features only. When true, `value` is a partial object
merged onto the feature's default value instead of replacing it.
type: boolean
required:
- type
- value
additionalProperties: false
FeatureRolloutRule:
allOf:
- description: >
Common fields shared by all feature rule types. Specific rule types
extend
this base with their own required properties (value, coverage,
etc.).
type: object
properties:
description:
type: string
maxLength: 10000
condition:
type: string
id:
type: string
enabled:
type: boolean
scheduleRules:
description: Simple time-based on/off schedule for this rule
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
scheduleType:
description: >
UI hint for which scheduling mode is active:
- `none` – no schedule
- `schedule` – simple time-based enable/disable via
`scheduleRules`
- `ramp` – multi-step ramp-up controlled by an associated
RampSchedule document
type: string
enum:
- none
- schedule
- ramp
rampScheduleId:
description: >-
ID of the active RampSchedule document controlling this rule.
Present when `scheduleType` is `ramp` and a live schedule
exists.
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 of the prerequisite
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
required:
- description
- id
- enabled
additionalProperties: false
- type: object
properties:
type:
type: string
const: rollout
value:
type: string
sparse:
description: >-
JSON features only. When true, `value` is a partial object
merged onto the feature's default value instead of replacing it.
type: boolean
coverage:
type: number
minimum: 0
maximum: 1
hashAttribute:
type: string
seed:
description: Optional seed for the hash function; defaults to the rule id
type: string
hashVersion:
description: >-
Hash algorithm version for bucketing. Defaults to 2 (preferred)
when not specified.
anyOf:
- type: number
const: 1
- type: number
const: 2
required:
- type
- value
- coverage
- hashAttribute
additionalProperties: false
FeatureExperimentRule:
allOf:
- description: >
Common fields shared by all feature rule types. Specific rule types
extend
this base with their own required properties (value, coverage,
etc.).
type: object
properties:
description:
type: string
maxLength: 10000
condition:
type: string
id:
type: string
enabled:
type: boolean
scheduleRules:
description: Simple time-based on/off schedule for this rule
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
scheduleType:
description: >
UI hint for which scheduling mode is active:
- `none` – no schedule
- `schedule` – simple time-based enable/disable via
`scheduleRules`
- `ramp` – multi-step ramp-up controlled by an associated
RampSchedule document
type: string
enum:
- none
- schedule
- ramp
rampScheduleId:
description: >-
ID of the active RampSchedule document controlling this rule.
Present when `scheduleType` is `ramp` and a live schedule
exists.
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 of the prerequisite
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
required:
- description
- id
- enabled
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment
trackingKey:
type: string
hashAttribute:
type: string
fallbackAttribute:
type: string
disableStickyBucketing:
type: boolean
bucketVersion:
type: number
minBucketVersion:
type: number
namespace:
type: object
properties:
enabled:
type: boolean
name:
type: string
range:
minItems: 2
maxItems: 2
type: array
items:
type: number
required:
- enabled
- name
- range
additionalProperties: false
coverage:
type: number
minimum: 0
maximum: 1
value:
description: Variation values with weights
type: array
items:
type: object
properties:
value:
type: string
weight:
type: number
name:
type: string
required:
- value
- weight
additionalProperties: false
required:
- type
additionalProperties: false
FeatureExperimentRefRule:
allOf:
- description: >
Common fields shared by all feature rule types. Specific rule types
extend
this base with their own required properties (value, coverage,
etc.).
type: object
properties:
description:
type: string
maxLength: 10000
condition:
type: string
id:
type: string
enabled:
type: boolean
scheduleRules:
description: Simple time-based on/off schedule for this rule
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
scheduleType:
description: >
UI hint for which scheduling mode is active:
- `none` – no schedule
- `schedule` – simple time-based enable/disable via
`scheduleRules`
- `ramp` – multi-step ramp-up controlled by an associated
RampSchedule document
type: string
enum:
- none
- schedule
- ramp
rampScheduleId:
description: >-
ID of the active RampSchedule document controlling this rule.
Present when `scheduleType` is `ramp` and a live schedule
exists.
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 of the prerequisite
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
required:
- description
- id
- enabled
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-ref
variations:
type: array
items:
type: object
properties:
value:
type: string
variationId:
type: string
required:
- value
- variationId
additionalProperties: false
experimentId:
type: string
sparse:
description: >-
JSON features only. When true, each variation `value` is a
partial object merged onto the feature's default value instead
of replacing it.
type: boolean
required:
- type
- variations
- experimentId
additionalProperties: false
FeatureSafeRolloutRule:
allOf:
- description: >
Common fields shared by all feature rule types. Specific rule types
extend
this base with their own required properties (value, coverage,
etc.).
type: object
properties:
description:
type: string
maxLength: 10000
condition:
type: string
id:
type: string
enabled:
type: boolean
scheduleRules:
description: Simple time-based on/off schedule for this rule
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
scheduleType:
description: >
UI hint for which scheduling mode is active:
- `none` – no schedule
- `schedule` – simple time-based enable/disable via
`scheduleRules`
- `ramp` – multi-step ramp-up controlled by an associated
RampSchedule document
type: string
enum:
- none
- schedule
- ramp
rampScheduleId:
description: >-
ID of the active RampSchedule document controlling this rule.
Present when `scheduleType` is `ramp` and a live schedule
exists.
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 of the prerequisite
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
required:
- description
- id
- enabled
additionalProperties: false
- type: object
properties:
type:
type: string
const: safe-rollout
controlValue:
type: string
variationValue:
type: string
seed:
type: string
hashAttribute:
type: string
trackingKey:
type: string
safeRolloutId:
type: string
status:
type: string
enum:
- running
- released
- rolled-back
- stopped
required:
- type
- controlValue
- variationValue
additionalProperties: false
ScheduleRule:
type: object
properties:
enabled:
description: >-
Whether the rule should be enabled or disabled at the specified
timestamp.
type: boolean
timestamp:
description: ISO timestamp when the rule should activate.
anyOf:
- format: date-time
type: string
- type: 'null'
required:
- enabled
- timestamp
additionalProperties: false
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >
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"
```
basicAuth:
type: http
scheme: basic
description: >
If using HTTP Basic auth, pass the Secret Key as the username and leave
the password blank:
```bash
curl https://api.growthbook.io/api/v1/features -u secret_abc123DEF456:
# The ":" at the end stops curl from asking for a password
```
````