> ## 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.
# Recall a review request (revert to draft)
> Retracts the review request, returning the revision from `pending-review`, `changes-requested`, or `approved` back to `draft`. Allowed for any user with draft-management permission on the feature (the same permission required to request review), not only the original requester. Existing review log entries are preserved as audit history but any in-flight reviewer verdicts (Approved / Requested Changes) submitted during this review cycle no longer count — submitting a fresh `request-review` starts a new cycle.
## OpenAPI
````yaml openapi.yaml POST /v2/features/{id}/revisions/{version}/recall-review
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}/revisions/{version}/recall-review:
post:
tags:
- feature-revisions-v2
summary: Recall a review request (revert to draft)
description: >-
Retracts the review request, returning the revision from
`pending-review`, `changes-requested`, or `approved` back to `draft`.
Allowed for any user with draft-management permission on the feature
(the same permission required to request review), not only the original
requester. Existing review log entries are preserved as audit history
but any in-flight reviewer verdicts (Approved / Requested Changes)
submitted during this review cycle no longer count — submitting a fresh
`request-review` starts a new cycle.
operationId: postFeatureRevisionRecallReviewV2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/recall-review'
\
-H 'Authorization: Bearer YOUR_API_KEY'
components:
parameters:
version:
name: version
in: path
required: true
description: ''
schema:
type: integer
schemas:
FeatureRevisionV2:
type: object
properties:
featureId:
description: The feature this revision belongs to
type: string
baseVersion:
type: integer
version:
type: integer
comment:
type: string
date:
format: date-time
type: string
status:
type: string
createdBy:
$ref: '#/components/schemas/EventUser'
publishedBy:
$ref: '#/components/schemas/EventUser'
defaultValue:
description: The default value at the time this revision was created
type: string
rules:
description: >-
Unified rules array. Each rule carries its own environment scope via
`allEnvironments` / `environments`.
type: array
items:
$ref: '#/components/schemas/FeatureRuleV2'
definitions:
type: object
propertyNames:
type: string
additionalProperties:
description: >-
A JSON stringified
[FeatureDefinition](#tag/FeatureDefinition_model)
type: string
environmentsEnabled:
description: >-
Per-environment enabled state captured in this revision (only
present when kill-switch gating is enabled)
type: object
propertyNames:
type: string
additionalProperties:
type: boolean
envPrerequisites:
description: >-
Per-environment prerequisites captured in this revision (only
present when prerequisite gating is enabled)
type: object
propertyNames:
type: string
additionalProperties:
type: array
items:
type: object
properties:
id:
description: Feature ID of the prerequisite boolean flag
type: string
required:
- id
additionalProperties: false
prerequisites:
description: >-
Feature-level prerequisites captured in this revision. Each entry is
a boolean flag ID that must evaluate to true for this flag to be
active for a given user.
type: array
items:
type: object
properties:
id:
description: Feature ID of the prerequisite boolean flag
type: string
required:
- id
additionalProperties: false
metadata:
description: >-
Metadata fields captured in this revision (only present when
metadata gating is enabled)
type: object
properties:
description:
type: string
maxLength: 10000
owner:
description: >-
The userId of the owner (or raw owner name/email for legacy
records)
type: string
project:
type: string
tags:
type: array
items:
type: string
neverStale:
type: boolean
valueType:
type: string
jsonSchema:
type: object
properties:
schemaType:
type: string
enum:
- schema
- simple
schema:
type: string
simple:
type: object
propertyNames:
type: string
additionalProperties: {}
date:
format: date-time
type: string
enabled:
type: boolean
additionalProperties: false
customFields:
type: object
propertyNames:
type: string
additionalProperties: {}
additionalProperties: false
rampActions:
description: >-
Pending ramp schedule actions that will be applied when this draft
is published
type: array
items:
anyOf:
- type: object
properties:
mode:
type: string
const: create
name:
type: string
environment:
anyOf:
- type: string
- type: 'null'
templateId:
type: string
startActions:
type: array
items:
type: object
properties:
targetType:
type: string
const: feature-rule
targetId:
type: string
patch:
type: object
properties:
ruleId:
type: string
coverage:
description: >-
Traffic fraction (0–1). For monitored steps the
rollout rule is promoted to an experiment:
treatment = [0, coverage), control = [0.5,
0.5+coverage). Both arms are equal-sized and
non-adjacent, so a step-up only adds new users
to each arm — no existing user changes group.
The REST API enforces coverage ≤ 0.5 on
monitored steps so control end never exceeds
1.0. The SDK uses explicit hash ranges on
bucketingV2 clients to keep bucketing stable
across monitored/unmonitored transitions.
anyOf:
- type: number
minimum: 0
maximum: 1
- type: 'null'
condition:
anyOf:
- type: string
- type: 'null'
savedGroups:
anyOf:
- type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
- type: 'null'
prerequisites:
anyOf:
- type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
- type: 'null'
allEnvironments:
anyOf:
- type: boolean
- type: 'null'
environments:
anyOf:
- type: array
items:
type: string
- type: 'null'
force:
description: Force value (any JSON type)
enabled:
anyOf:
- type: boolean
- type: 'null'
additionalProperties: false
required:
- patch
additionalProperties: false
steps:
type: array
items:
type: object
properties:
interval:
anyOf:
- type: number
exclusiveMinimum: 0
- type: 'null'
actions:
type: array
items:
type: object
properties:
targetType:
type: string
const: feature-rule
targetId:
type: string
patch:
type: object
properties:
ruleId:
type: string
coverage:
description: >-
Traffic fraction (0–1). For monitored
steps the rollout rule is promoted to an
experiment: treatment = [0, coverage),
control = [0.5, 0.5+coverage). Both arms
are equal-sized and non-adjacent, so a
step-up only adds new users to each arm —
no existing user changes group. The REST
API enforces coverage ≤ 0.5 on monitored
steps so control end never exceeds 1.0.
The SDK uses explicit hash ranges on
bucketingV2 clients to keep bucketing
stable across monitored/unmonitored
transitions.
anyOf:
- type: number
minimum: 0
maximum: 1
- type: 'null'
condition:
anyOf:
- type: string
- type: 'null'
savedGroups:
anyOf:
- type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
- type: 'null'
prerequisites:
anyOf:
- type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
- type: 'null'
allEnvironments:
anyOf:
- type: boolean
- type: 'null'
environments:
anyOf:
- type: array
items:
type: string
- type: 'null'
force:
description: Force value (any JSON type)
enabled:
anyOf:
- type: boolean
- type: 'null'
additionalProperties: false
required:
- patch
additionalProperties: false
approvalNotes:
anyOf:
- type: string
- type: 'null'
monitored:
type: boolean
holdConditions:
type: object
properties:
minSampleSize:
type: integer
exclusiveMinimum: 0
requiresApproval:
type: boolean
additionalProperties: false
required:
- interval
additionalProperties: false
endActions:
type: array
items:
type: object
properties:
targetType:
type: string
const: feature-rule
targetId:
type: string
patch:
type: object
properties:
ruleId:
type: string
coverage:
description: >-
Traffic fraction (0–1). For monitored steps the
rollout rule is promoted to an experiment:
treatment = [0, coverage), control = [0.5,
0.5+coverage). Both arms are equal-sized and
non-adjacent, so a step-up only adds new users
to each arm — no existing user changes group.
The REST API enforces coverage ≤ 0.5 on
monitored steps so control end never exceeds
1.0. The SDK uses explicit hash ranges on
bucketingV2 clients to keep bucketing stable
across monitored/unmonitored transitions.
anyOf:
- type: number
minimum: 0
maximum: 1
- type: 'null'
condition:
anyOf:
- type: string
- type: 'null'
savedGroups:
anyOf:
- type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
- type: 'null'
prerequisites:
anyOf:
- type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
- type: 'null'
allEnvironments:
anyOf:
- type: boolean
- type: 'null'
environments:
anyOf:
- type: array
items:
type: string
- type: 'null'
force:
description: Force value (any JSON type)
enabled:
anyOf:
- type: boolean
- type: 'null'
additionalProperties: false
required:
- patch
additionalProperties: false
startDate:
description: >-
ISO 8601 date-time, e.g. "2025-06-01T00:00:00Z". Absent or
null means start immediately on publish.
anyOf:
- format: date-time
type: string
- type: 'null'
cutoffDate:
description: >-
ISO 8601 date-time, e.g. "2025-07-01T00:00:00Z". The ramp
ends at this time.
anyOf:
- format: date-time
type: string
- type: 'null'
ruleId:
type: string
monitoringConfig:
type: object
properties:
datasourceId:
type: string
exposureQueryId:
type: string
guardrailMetricIds:
minItems: 1
type: array
items:
type: string
signalMetricIds:
type: array
items:
type: string
updateScheduleMinutes:
anyOf:
- type: number
minimum: 10
- type: 'null'
monitoringMode:
type: string
enum:
- auto
- manual
autoUpdate:
type: boolean
srmAction:
type: string
enum:
- rollback
- hold
- warn
noTrafficAction:
type: string
enum:
- rollback
- hold
- warn
noTrafficGracePeriodHours:
description: >-
How long to wait for traffic before applying
`noTrafficAction`. Defaults to 24 hours when null or
not set.
anyOf:
- type: number
exclusiveMinimum: 0
- type: 'null'
multipleExposureAction:
type: string
enum:
- rollback
- hold
- warn
required:
- datasourceId
- exposureQueryId
- guardrailMetricIds
additionalProperties: false
lockdownConfig:
type: object
properties:
mode:
type: string
enum:
- none
- locked
required:
- mode
additionalProperties: false
required:
- mode
- ruleId
additionalProperties: false
- type: object
properties:
name:
type: string
environment:
anyOf:
- type: string
- type: 'null'
templateId:
type: string
startActions:
type: array
items:
type: object
properties:
targetType:
type: string
const: feature-rule
targetId:
type: string
patch:
type: object
properties:
ruleId:
type: string
coverage:
description: >-
Traffic fraction (0–1). For monitored steps the
rollout rule is promoted to an experiment:
treatment = [0, coverage), control = [0.5,
0.5+coverage). Both arms are equal-sized and
non-adjacent, so a step-up only adds new users
to each arm — no existing user changes group.
The REST API enforces coverage ≤ 0.5 on
monitored steps so control end never exceeds
1.0. The SDK uses explicit hash ranges on
bucketingV2 clients to keep bucketing stable
across monitored/unmonitored transitions.
anyOf:
- type: number
minimum: 0
maximum: 1
- type: 'null'
condition:
anyOf:
- type: string
- type: 'null'
savedGroups:
anyOf:
- type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
- type: 'null'
prerequisites:
anyOf:
- type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
- type: 'null'
allEnvironments:
anyOf:
- type: boolean
- type: 'null'
environments:
anyOf:
- type: array
items:
type: string
- type: 'null'
force:
description: Force value (any JSON type)
enabled:
anyOf:
- type: boolean
- type: 'null'
additionalProperties: false
required:
- patch
additionalProperties: false
steps:
type: array
items:
type: object
properties:
interval:
anyOf:
- type: number
exclusiveMinimum: 0
- type: 'null'
actions:
type: array
items:
type: object
properties:
targetType:
type: string
const: feature-rule
targetId:
type: string
patch:
type: object
properties:
ruleId:
type: string
coverage:
description: >-
Traffic fraction (0–1). For monitored
steps the rollout rule is promoted to an
experiment: treatment = [0, coverage),
control = [0.5, 0.5+coverage). Both arms
are equal-sized and non-adjacent, so a
step-up only adds new users to each arm —
no existing user changes group. The REST
API enforces coverage ≤ 0.5 on monitored
steps so control end never exceeds 1.0.
The SDK uses explicit hash ranges on
bucketingV2 clients to keep bucketing
stable across monitored/unmonitored
transitions.
anyOf:
- type: number
minimum: 0
maximum: 1
- type: 'null'
condition:
anyOf:
- type: string
- type: 'null'
savedGroups:
anyOf:
- type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
- type: 'null'
prerequisites:
anyOf:
- type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
- type: 'null'
allEnvironments:
anyOf:
- type: boolean
- type: 'null'
environments:
anyOf:
- type: array
items:
type: string
- type: 'null'
force:
description: Force value (any JSON type)
enabled:
anyOf:
- type: boolean
- type: 'null'
additionalProperties: false
required:
- patch
additionalProperties: false
approvalNotes:
anyOf:
- type: string
- type: 'null'
monitored:
type: boolean
holdConditions:
type: object
properties:
minSampleSize:
type: integer
exclusiveMinimum: 0
requiresApproval:
type: boolean
additionalProperties: false
required:
- interval
additionalProperties: false
endActions:
type: array
items:
type: object
properties:
targetType:
type: string
const: feature-rule
targetId:
type: string
patch:
type: object
properties:
ruleId:
type: string
coverage:
description: >-
Traffic fraction (0–1). For monitored steps the
rollout rule is promoted to an experiment:
treatment = [0, coverage), control = [0.5,
0.5+coverage). Both arms are equal-sized and
non-adjacent, so a step-up only adds new users
to each arm — no existing user changes group.
The REST API enforces coverage ≤ 0.5 on
monitored steps so control end never exceeds
1.0. The SDK uses explicit hash ranges on
bucketingV2 clients to keep bucketing stable
across monitored/unmonitored transitions.
anyOf:
- type: number
minimum: 0
maximum: 1
- type: 'null'
condition:
anyOf:
- type: string
- type: 'null'
savedGroups:
anyOf:
- type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
- type: 'null'
prerequisites:
anyOf:
- type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
- type: 'null'
allEnvironments:
anyOf:
- type: boolean
- type: 'null'
environments:
anyOf:
- type: array
items:
type: string
- type: 'null'
force:
description: Force value (any JSON type)
enabled:
anyOf:
- type: boolean
- type: 'null'
additionalProperties: false
required:
- patch
additionalProperties: false
startDate:
description: >-
ISO 8601 date-time, e.g. "2025-06-01T00:00:00Z". Absent or
null means start immediately on publish.
anyOf:
- format: date-time
type: string
- type: 'null'
cutoffDate:
description: >-
ISO 8601 date-time, e.g. "2025-07-01T00:00:00Z". The ramp
ends at this time.
anyOf:
- format: date-time
type: string
- type: 'null'
ruleId:
type: string
monitoringConfig:
type: object
properties:
datasourceId:
type: string
exposureQueryId:
type: string
guardrailMetricIds:
minItems: 1
type: array
items:
type: string
signalMetricIds:
type: array
items:
type: string
updateScheduleMinutes:
anyOf:
- type: number
minimum: 10
- type: 'null'
monitoringMode:
type: string
enum:
- auto
- manual
autoUpdate:
type: boolean
srmAction:
type: string
enum:
- rollback
- hold
- warn
noTrafficAction:
type: string
enum:
- rollback
- hold
- warn
noTrafficGracePeriodHours:
description: >-
How long to wait for traffic before applying
`noTrafficAction`. Defaults to 24 hours when null or
not set.
anyOf:
- type: number
exclusiveMinimum: 0
- type: 'null'
multipleExposureAction:
type: string
enum:
- rollback
- hold
- warn
required:
- datasourceId
- exposureQueryId
- guardrailMetricIds
additionalProperties: false
lockdownConfig:
type: object
properties:
mode:
type: string
enum:
- none
- locked
required:
- mode
additionalProperties: false
mode:
type: string
const: update
rampScheduleId:
type: string
required:
- ruleId
- mode
- rampScheduleId
additionalProperties: false
- type: object
properties:
mode:
type: string
const: detach
rampScheduleId:
type: string
ruleId:
type: string
deleteScheduleWhenEmpty:
type: boolean
required:
- mode
- rampScheduleId
- ruleId
additionalProperties: false
autoPublishOnApproval:
description: >-
When true, the revision is armed to publish automatically once
governance allows (immediately on approval, or on
`scheduledPublishAt` if set).
type: boolean
scheduledPublishAt:
description: >-
Target date for a deferred (scheduled) publish. Null/absent means
publish as soon as approved.
anyOf:
- format: date-time
type: string
- type: 'null'
scheduledPublishLockEdits:
description: >-
When true, content edits to this draft are frozen while the schedule
is pending (rebasing is still allowed).
type: boolean
scheduledPublishLockOthers:
description: >-
When true, publishing other drafts of this feature is blocked while
the schedule is pending.
type: boolean
scheduledPublishBypassApproval:
description: >-
When true, this schedule was armed by an admin via the
bypass-approval override. It cannot be edited inline (only canceled
and re-armed) and anyone with publish authority may cancel it.
type: boolean
scheduledPublishLastError:
description: >-
Set when a due scheduled publish keeps failing (e.g. still awaiting
approval, merge conflict). Indicates the schedule is stuck and
retrying.
type: string
reviews:
description: >-
Reviewer verdicts for the current review cycle (one entry per
reviewer). Verdicts flip to their -stale variants when draft content
changes after submission; the list is cleared when a new review
cycle starts. Absent on revisions that predate this field.
type: array
items:
type: object
properties:
userId:
description: >-
Stable reviewer identifier: the user ID for dashboard users,
or the API key ID for service accounts
type: string
user:
$ref: '#/components/schemas/EventUser'
status:
type: string
enum:
- approved
- changes-requested
- approved-stale
- changes-requested-stale
timestamp:
format: date-time
type: string
required:
- userId
- status
- timestamp
additionalProperties: false
required:
- featureId
- baseVersion
- version
- comment
- date
- status
- rules
additionalProperties: false
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
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
FeatureRuleV1:
anyOf:
- $ref: '#/components/schemas/FeatureForceRule'
- $ref: '#/components/schemas/FeatureRolloutRule'
- $ref: '#/components/schemas/FeatureExperimentRule'
- $ref: '#/components/schemas/FeatureExperimentRefRule'
- $ref: '#/components/schemas/FeatureSafeRolloutRule'
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
```
````