> ## Documentation Index
> Fetch the complete documentation index at: https://docs.growthbook.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Set archived state in a draft revision
## OpenAPI
````yaml openapi.yaml PUT /v2/features/{id}/revisions/{version}/archive
openapi: 3.1.0
info:
version: 5.1.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. Feature-flag and metric
v1 routes are deprecated: they are tagged **LEGACY** in the sidebar and
collapsed by default. Use the matching v2 group when both exist.
## Authentication
We support both the HTTP Basic and Bearer authentication schemes for
convenience.
You first need to generate a new API Key in GrowthBook. Different keys have
different permissions:
- **Personal Access Tokens**: These are sensitive and provide the same level
of access as the user has to an organization, or less if the token's
permissions are limited. These can be created by going to `Personal Access
Tokens` under your user menu. Members with the API Keys **Manage members'
tokens** permission can disable a member's token under `Settings -> Manage
PATs`, and admins can require new tokens to expire within a maximum
lifetime.
- **Secret Keys**: These are sensitive and provide the level of access of
the role they are given, which can be any built-in or custom role, with
optional per-project role overrides and environment limits. Managing Secret
Keys on behalf of an organization takes the [API Keys
permissions](/account/user-permissions). These can be created by going to
`Settings -> API Keys`, where Admins can also require new Secret Keys to
expire within a maximum lifetime.
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"
```
If a key has an expiration date, every response includes it in the
`X-GrowthBook-Key-Expires-At` header (ISO 8601), so scripts can warn before
the key stops working. Requests made with an expired key fail with a `401`
that says where to create a replacement. See
[Expiration](/integrations/ai-agents/api-keys#expiration) for choosing a
key's expiration, the warnings before it lapses, and the organization
policies.
## Naming who asked
Requests made with a Secret Key may add an `X-GrowthBook-Requested-By`
header naming the organization member who asked for the change, as a user id
or an email address. History, revision logs and webhooks show that member
next to the key.
Each key acts as **System** (the default) or **User**, set under `Settings
-> API Keys`:
- **System**: the header is optional. The key acts as itself, with its own
permissions, and the named member is only recorded in history.
- **User**: a request without the header is rejected with a 400. The request
acts as the named member, with only what both the key and the member can do,
so the header can narrow a key but never widen it. Drafts, owners, `mine`
filters and reviews are the member's. The member's rights over their own
drafts, comments and verdicts apply only where the key's own role allows the
same action.
A System key, or any key that names no one, acts as itself: it can draft and
review with its own permissions, and its verdicts are judged on its role. A
key belongs to no team, so its approval never satisfies a rule that requires
approval from a team. No one can rule on a draft they created, and a key
acting as itself can't rule on a draft it created or edited. An approval a
User key gives counts only where both the key and the member could approve,
and stops counting if the key is disabled, expires or is deleted. Because
the header isn't verified, whoever holds the key can act as any member. A
value that does not match a member of the organization is rejected with a
400. A create request that omits `owner` defaults it to the member a User
key names. Scheduled and auto-publishes run later with the permissions of
the request that armed them, and don't run if that member has left the
organization, the key has expired, or the key no longer acts as User.
Personal Access Tokens and OAuth tokens already act as their user and reject
the header.
```bash
curl https://api.growthbook.io/api/v1/features \
-H "Authorization: Bearer secret_abc123DEF456" \
-H "X-GrowthBook-Requested-By: alice@example.com"
```
## Naming and human review
People review what the API creates in the GrowthBook UI.
- Keep keys and names short (2-5 words). Follow your organization's Feature
Flag key format (`featureRegexValidator` and `featureKeyExample` in `GET
/v1/settings`), or use kebab-case if it has none. Feature Flag keys can't be
changed after creation, and an experiment's tracking key shouldn't change
after launch.
- Put context (why, plan, tickets, links) in `description`, not in names or
keys.
- Group with `tags`, not name prefixes. Projects (`project` or `projects`)
control access and where a resource can be used, so set them deliberately
instead of using them as labels.
- To create a Feature Flag disabled with `POST /v2/features`, list every
environment in `environments` with `enabled: false` (on `POST /v1/features`,
each entry also needs `rules: []`). An environment you leave out uses its
default state, which may be enabled.
- Leave publishing and production changes to a person unless asked.
- If a request is blocked (an approval requirement, a warning, a Custom
Hook, schema validation or a permission error), stop and ask a person. Don't
retry with an override field, a different key or another workaround unless a
person asked you to. If a write answers `202` with a `confirmation`, give a
person its `url` and wait (see [Waiting for
confirmation](#waiting-for-confirmation)).
## Waiting for confirmation
A key can require a person to confirm some writes before they run (see [API
Keys for Agents](/integrations/ai-agents/api-keys#require-confirmation)). A
held write doesn't run. It answers `202 Accepted` with the confirmation, a
`Location` header to poll, and a `Retry-After` header with the seconds to
wait between polls:
```json
{
"confirmation": {
"id": "cnf_abc123",
"status": "pending",
"actions": [
{ "action": "feature.publish", "environments": ["production"] }
],
"summary": "Publish revision 3 of checkout-redesign",
"url": "https://app.growthbook.io/confirmations/cnf_abc123",
"expiresAt": "2026-10-15T18:00:00.000Z",
"response": null,
"note": null
},
"message": "A person must confirm this in GrowthBook. Give them the url, then poll the Location."
}
```
Give the person the `url`, then poll [`GET
/v1/confirmations/{id}`](/api/meta/operation/getConfirmation). Pass `wait`
(in seconds, up to 30) to hold the poll open until the status changes:
```bash
curl "https://api.growthbook.io/api/v1/confirmations/cnf_abc123?wait=30" \
-H "Authorization: Bearer secret_abc123DEF456"
```
| `status` |
Meaning
|
| ----------- |
---------------------------------------------------------------------------------------------------------------------
|
| `pending` | Waiting for a person, until `expiresAt` (an hour after the
request) |
| `running` | Confirmed, and running
now
|
| `completed` | It ran. `response` holds the status and body the request
returned, which may be an error |
| `rejected` | A person declined it, and nothing
ran
|
| `expired` | Nobody decided in time, or it acts on something that changed
after it was held (with a `400` `response`). Nothing ran |
`note` carries anything the person left for the agent when they decided.
`actions` lists what the request was held for, each with the environments it
touches.
- Only the key that made the request, or another token of the same person,
can read the confirmation.
- Sending the same request again while it's pending returns the same
confirmation.
- A request that publishes, reverts or archives, or that changes a Feature
Flag or an Experiment's status, schedule, targeting or traffic, isn't run if
what it acts on changed after it was held. Other writes, such as editing
settings or a draft, run as sent, so they can overwrite changes made while
they waited.
- A confirmed request runs once, with the key's permissions (or the member's
role it assumes), not the confirmer's. Send it again to retry, which asks
for a new confirmation.
- Confirming isn't a review approval.
## 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** - Unprocessable Entity - The request is valid, but a warning,
validation rule, approval requirement, or another publishing gate blocked
it. Do not assume that `ignoreWarnings` clears every 422 response.
- **429** - Too Many Requests - You exceeded the rate limit of 60 requests
per minute, or the limit your self-hosted server sets. 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
### Publishing gates
Automated callers, including AI agents, should report a blocked response to
a person instead of retrying with an override. Use an override only when a
person has explicitly asked for it.
Publish responses include a `gates` array that explains every blocker:
- `type`, `severity`, and `messages` identify the problem.
- `override` names the request-body field that can bypass it. This is
`ignoreWarnings` for warnings, `skipSchemaValidation` for schema and
invariant failures, or `skipHooks` for Custom Hook rejections. A value of
`null` means there is no request-body override.
- `requiresPermission` identifies any additional permission needed to use
the override.
- `resolution` provides an API action, method, and path when the blocker
must be resolved another way.
For example, an approval gate is cleared by approving the revision or by
using a caller with **Bypass draft approvals** access. A Config lock is
cleared through the unlock route in `resolution`.
When a successful publish bypasses a gate, the response includes
`bypassedGates`. Each entry reports the gate `type` and how it was bypassed
in `via`, which is one of `ignoreWarnings`, `skipSchemaValidation`,
`skipHooks`, `bypassApprovalPermission`, `restApiBypassesReviews`, or
`revertsBypassApproval` (reverts only). This field is omitted when no gates
were bypassed.
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 programmatically.
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 programmatically.
**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: constants
x-displayName: Constants
description: >-
**Beta** — these endpoints are new and may change in
backwards-incompatible ways.
Reusable named values referenced from feature flag values as `@const:key`
and resolved into the SDK payload at build time. String constants are
interpolated via `{{ @const:key }}`; JSON (object) constants are composed
via an `$extends` array. A constant's own keys **replace** what its
`$extends` bases provide, wholesale — constants are atomic building
blocks. (Config and feature values compose as deep, targeted patches
instead.)
- name: constant-revisions
x-displayName: Constant Revisions
description: >-
**Beta** — these endpoints are new and may change in
backwards-incompatible ways.
Draft revisions for constants, including pending changes, approvals, and
lifecycle (publish, discard, revert). Pass `version: "new"` on edit
endpoints to auto-create a draft.
- name: configs
x-displayName: Configs
description: >-
**Beta** — these endpoints are new and may change in
backwards-incompatible ways.
Reusable, typed, inheritable JSON objects referenced from feature flag
values as `@config:key`. A config carries a field `schema` (with
TypeScript/JSON Schema import-export) and a lineage `parent`. Inheritance
is expressed via `parent`, never an in-value `@config:` entry. Values
layer as a **deep, targeted patch**: a child (or a config-backed feature
value) restates only the leaves it changes and inherits the rest — unlike
a constant's `$extends`, whose own keys replace wholesale. Schema fields
colliding with a published ancestor's key follow 'base wins': identical
re-declarations are stripped with a warning, differing ones are rejected.
- name: config-revisions
x-displayName: Config Revisions
description: >-
**Beta** — these endpoints are new and may change in
backwards-incompatible ways.
Draft revisions for configs, including value and schema edits, schema
import (JSON Schema / TypeScript / inferred), approvals, and lifecycle
(publish, discard, revert). Publishing a schema change cascades the "base
wins" normalization to descendant configs; a publish that removes or
retypes fields descendants still use soft-blocks with a 422 unless the
request body sets `ignoreWarnings: true`. 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: custom-hooks
x-displayName: Custom Hooks
description: >-
Sandboxed JavaScript validation hooks that run when features, configs, or
their revisions are saved or published. Throwing an Error blocks the save;
`addWarning(msg)` raises a soft warning. Hooks are scoped by projects, or
pinned to a single feature/config via `entityType`/`entityId`; a
config-scoped hook also runs for every config inheriting from it (its
whole descendant lineage). Scope can be retargeted on update (or cleared
with nulls). Requires an enterprise plan; not available on GrowthBook
Cloud.
- 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: ContextualBandits
x-displayName: Contextual Bandits
description: ''
- name: Dashboards
x-displayName: Dashboards
description: ''
- name: ContextualBanditQueries
x-displayName: Contextual Bandit Queries
description: ''
- name: Interleavings
x-displayName: Interleaving Experiments
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: Learnings
x-displayName: Learnings
description: >-
Saved learnings captured across experiments, including AI-discovered
patterns.
- name: Holdouts
x-displayName: Holdouts
description: >-
Hold a share of traffic out of all experiments to measure their combined
effect.
- name: AutoRuns
x-displayName: Auto Runs
description: ''
- name: Populations
x-displayName: Populations
description: >-
**Beta** — these endpoints are new and may change in
backwards-incompatible ways.
Populations define a set of units by the steps they must complete, such as
appearing in a fact table. Populations are not yet used in analysis.
- 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: AutoRun_model
x-displayName: Auto Run
description:
- name: CodeRef_model
x-displayName: Code Ref
description:
- name: Config_model
x-displayName: Config
description:
- name: ConfigKeyUsage_model
x-displayName: Config Key Usage
description:
- name: ConfigLineage_model
x-displayName: Config Lineage
description:
- name: ConfigReferences_model
x-displayName: Config References
description:
- name: ConfigRevision_model
x-displayName: Config Revision
description:
- name: ConfigRevisionActivityLogEntry_model
x-displayName: Config Revision Activity Log Entry
description: >-
- name: ConfigRevisionRef_model
x-displayName: Config Revision Ref
description:
- name: ConfigRevisionReview_model
x-displayName: Config Revision Review
description:
- name: ConfigSchemaExport_model
x-displayName: Config Schema Export
description:
- name: ConfigSchemaSource_model
x-displayName: Config Schema Source
description:
- name: ConfigSchemaVerify_model
x-displayName: Config Schema Verify
description:
- name: ConfigSchemaWarning_model
x-displayName: Config Schema Warning
description:
- name: Confirmation_model
x-displayName: Confirmation
description:
- name: ConfirmationHeld_model
x-displayName: Confirmation Held
description:
- name: Constant_model
x-displayName: Constant
description:
- name: ConstantReferences_model
x-displayName: Constant References
description:
- name: ConstantRevision_model
x-displayName: Constant Revision
description:
- name: ConstantRevisionActivityLogEntry_model
x-displayName: Constant Revision Activity Log Entry
description: >-
- name: ConstantRevisionRef_model
x-displayName: Constant Revision Ref
description:
- name: ConstantRevisionReview_model
x-displayName: Constant Revision Review
description: >-
- name: ContextualBandit_model
x-displayName: Contextual Bandit
description:
- name: ContextualBanditQuery_model
x-displayName: Contextual Bandit Query
description: >-
- name: CustomField_model
x-displayName: Custom Field
description:
- name: CustomHook_model
x-displayName: Custom Hook
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: FeatureContextualBanditRefRule_model
x-displayName: Feature Contextual Bandit Ref 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: FeatureRevisionRef_model
x-displayName: Feature Revision Ref
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: Holdout_model
x-displayName: Holdout
description:
- name: InformationSchema_model
x-displayName: Information Schema
description:
- name: InformationSchemaTable_model
x-displayName: Information Schema Table
description: >-
- name: Interleaving_model
x-displayName: Interleaving
description:
- name: Learning_model
x-displayName: Learning
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: Population_model
x-displayName: Population
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: RequireReviewRule_model
x-displayName: Require Review Rule
description:
- name: RequireReviewRuleInput_model
x-displayName: Require Review Rule Input
description: >-
- name: RevisionIdRef_model
x-displayName: Revision Id Ref
description:
- name: Safe Rollout Rule_model
x-displayName: Safe Rollout Rule
description:
- name: SavedGroup_model
x-displayName: Saved Group
description:
- name: SavedGroupApprovalRule_model
x-displayName: Saved Group Approval Rule
description: >-
- name: SavedGroupReferenceResource_model
x-displayName: Saved Group Reference Resource
description: >-
- name: SavedGroupReferences_model
x-displayName: Saved Group References
description:
- name: SavedGroupRevision_model
x-displayName: Saved Group Revision
description:
- name: SavedGroupRevisionActivityLogEntry_model
x-displayName: Saved Group Revision Activity Log Entry
description: >-
- name: SavedGroupRevisionRef_model
x-displayName: Saved Group Revision Ref
description: >-
- name: SavedGroupRevisionReview_model
x-displayName: Saved Group Revision Review
description: >-
- name: ScheduleRule_model
x-displayName: Schedule Rule
description:
- name: ScheduledStopPlan_model
x-displayName: Scheduled Stop Plan
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: TargetingReviewRule_model
x-displayName: Targeting Review 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:
- name: VisualEditorCbExperimentStub_model
x-displayName: Visual Editor Cb Experiment Stub
description: >-
paths:
/v2/features/{id}/revisions/{version}/archive:
put:
tags:
- feature-revisions-v2
summary: Set archived state in a draft revision
operationId: putFeatureRevisionArchiveV2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- name: version
in: path
required: true
description: ''
schema:
anyOf:
- type: integer
- type: string
const: new
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
archived:
type: boolean
revisionTitle:
description: >-
Short draft title (e.g. `Enable for beta testers`). Only
used when `version` is "new"; ignored for existing drafts.
type: string
revisionComment:
description: >-
Markdown. What changed and why, for reviewers. Only used
when `version` is "new"; ignored for existing drafts.
type: string
ignoreWarnings:
description: >-
Set to true to acknowledge the warnings listed in a blocked
response and continue. This covers experiment guards, locked
dependents, and references affected by an archive. When the
organization treats schema failures as warnings, it also
covers schema and invariant warnings. It never bypasses a
rejected Custom Hook. On revision publish endpoints, it can
also force-publish an out-of-date draft when the caller has
Bypass draft approvals access. Only set this when a person
has explicitly asked you to. If a check blocks you, stop and
ask a person instead of working around it.
type: boolean
required:
- archived
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/archive'
\
-H 'Authorization: Bearer YOUR_API_KEY'
components:
schemas:
FeatureRevisionV2:
type: object
properties:
id:
description: >-
Stable revision id. Newer revisions carry opaque ids; older ones a
derived `frev__` form. Both work wherever
revision ids are accepted.
type: string
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. When the
feature is in Config mode, this is the JSON override patch merged on
top of the config (its own keys win); otherwise it is the full
value.
type: string
defaultValueConfig:
description: >-
Optional. A config within `baseConfig`'s family that the default
value resolves to instead of `baseConfig` itself. null or omitted
means the default is `baseConfig`. The default is exactly this
config and carries no overrides of its own.
anyOf:
- type: string
- type: 'null'
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: {}
baseConfig:
anyOf:
- type: string
- type: 'null'
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: >-
Value to serve, in the string form rule values
use ("false", "10", '{"limit": 5}'). A
non-string JSON value is accepted and stored as
its JSON text. Must be valid for the feature's
value type.
enabled:
anyOf:
- type: boolean
- type: 'null'
hashAttribute:
description: >-
Attribute the rule buckets on. Required (here or
on the rule) when a step sets partial coverage
on a force rule, which becomes a rollout.
anyOf:
- type: string
- type: 'null'
seed:
description: >-
Hash seed for a promoted force rule. Defaults to
the rule id.
anyOf:
- type: string
- type: 'null'
hashVersion:
description: >-
Hash algorithm version for a promoted force
rule. Defaults to 2.
anyOf:
- anyOf:
- type: number
const: 1
- type: number
const: 2
- 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: >-
Value to serve, in the string form rule
values use ("false", "10", '{"limit":
5}'). A non-string JSON value is accepted
and stored as its JSON text. Must be valid
for the feature's value 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: >-
Value to serve, in the string form rule values
use ("false", "10", '{"limit": 5}'). A
non-string JSON value is accepted and stored as
its JSON text. Must be valid for the feature's
value 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
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
exposureQuery:
description: >-
The assignment query, grouping its ID with the
identifier type analyzed on.
type: object
properties:
id:
description: >-
The ID of one of the data source's assignment
queries.
type: string
identifierType:
description: >-
The identifier type analyzed on. Null when none
can be resolved: no assignment query is selected,
or a record saved before identifier types were
stored points at a query that no longer exists.
anyOf:
- type: string
- type: 'null'
required:
- id
- identifierType
additionalProperties: false
exposureQueryId:
description: 'Deprecated: use `exposureQuery`.'
deprecated: true
type: string
required:
- datasourceId
- guardrailMetricIds
- exposureQuery
- exposureQueryId
additionalProperties: false
lockdownConfig:
type: object
properties:
mode:
type: string
enum:
- none
- locked
required:
- mode
additionalProperties: false
requiresStartApproval:
anyOf:
- type: boolean
- type: 'null'
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: >-
Value to serve, in the string form rule values
use ("false", "10", '{"limit": 5}'). A
non-string JSON value is accepted and stored as
its JSON text. Must be valid for the feature's
value type.
enabled:
anyOf:
- type: boolean
- type: 'null'
hashAttribute:
description: >-
Attribute the rule buckets on. Required (here or
on the rule) when a step sets partial coverage
on a force rule, which becomes a rollout.
anyOf:
- type: string
- type: 'null'
seed:
description: >-
Hash seed for a promoted force rule. Defaults to
the rule id.
anyOf:
- type: string
- type: 'null'
hashVersion:
description: >-
Hash algorithm version for a promoted force
rule. Defaults to 2.
anyOf:
- anyOf:
- type: number
const: 1
- type: number
const: 2
- 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: >-
Value to serve, in the string form rule
values use ("false", "10", '{"limit":
5}'). A non-string JSON value is accepted
and stored as its JSON text. Must be valid
for the feature's value 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: >-
Value to serve, in the string form rule values
use ("false", "10", '{"limit": 5}'). A
non-string JSON value is accepted and stored as
its JSON text. Must be valid for the feature's
value 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
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
exposureQuery:
description: >-
The assignment query, grouping its ID with the
identifier type analyzed on.
type: object
properties:
id:
description: >-
The ID of one of the data source's assignment
queries.
type: string
identifierType:
description: >-
The identifier type analyzed on. Null when none
can be resolved: no assignment query is selected,
or a record saved before identifier types were
stored points at a query that no longer exists.
anyOf:
- type: string
- type: 'null'
required:
- id
- identifierType
additionalProperties: false
exposureQueryId:
description: 'Deprecated: use `exposureQuery`.'
deprecated: true
type: string
required:
- datasourceId
- guardrailMetricIds
- exposureQuery
- exposureQueryId
additionalProperties: false
lockdownConfig:
type: object
properties:
mode:
type: string
enum:
- none
- locked
required:
- mode
additionalProperties: false
requiresStartApproval:
anyOf:
- type: boolean
- type: 'null'
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: >-
Whether the schedule was created for an unapproved draft by a caller
with Bypass draft approvals access. This kind of schedule cannot be
edited; cancel it and create a new schedule instead. Anyone with
Publish access can 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
autoPublishEnabledBy:
description: >-
User or API key the deferred publish runs as, re-checked when it
fires. A key that assumed a member's role is recorded as
`:`.
type: string
autoPublishEnabledByUser:
$ref: '#/components/schemas/EventUser'
description: Who armed the deferred publish, with an API key's name
scheduledPublishAttempts:
description: >-
How many times the poller has tried to publish this revision. Read
with `scheduledPublishGaveUpAt` to tell a schedule that is still
retrying from one that has been parked.
type: integer
scheduledPublishGaveUpAt:
format: date-time
description: >-
When the poller stopped retrying. Giving up CLEARS the schedule and
disarms auto-publish, so nothing fires again until the revision is
re-armed. The draft is left open, with `scheduledPublishLastError`
preserved for context.
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: >-
Who reviewed: a member's user ID, or an API key's ID when it
reviewed as itself
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:
- id
- featureId
- baseVersion
- version
- comment
- date
- status
- rules
additionalProperties: false
EventUser:
description: Who performed an action
type: object
properties:
type:
description: >-
`dashboard` (signed-in member), `api_key` (API key or personal
access token) or `system`
type: string
enum:
- dashboard
- api_key
- system
id:
description: The member's user ID. Absent for an organization API key
type: string
apiKey:
description: The API key's ID, when the action came through one
type: string
name:
description: The member's name, or the organization API key's name
type: string
email:
description: The member's email. Absent for an organization API key
type: string
requestedBy:
description: The member named with `X-GrowthBook-Requested-By`
type: object
properties:
id:
type: string
name:
type: string
email:
type: string
required:
- id
- name
- email
additionalProperties: false
assumedRole:
description: Whether the key assumed the named member's role
type: boolean
required:
- type
additionalProperties: false
FeatureRuleV2:
allOf:
- anyOf:
- allOf:
- $ref: '#/components/schemas/FeatureForceRule'
- type: object
properties:
config:
description: >-
Key of the config backing this value, or null when the
value is not config-backed. The config supplies the base
JSON (and its schema); the value is an override patch
merged on top.
anyOf:
- type: string
- type: 'null'
additionalProperties: false
- allOf:
- $ref: '#/components/schemas/FeatureRolloutRule'
- type: object
properties:
config:
description: >-
Key of the config backing this value, or null when the
value is not config-backed. The config supplies the base
JSON (and its schema); the value is an override patch
merged on top.
anyOf:
- type: string
- type: 'null'
additionalProperties: false
- $ref: '#/components/schemas/FeatureExperimentRule'
title: Feature Experiment Rule
- allOf:
- $ref: '#/components/schemas/FeatureBaseRule'
- type: object
properties:
type:
type: string
const: experiment-ref
variations:
type: array
items:
type: object
properties:
value:
type: string
variationId:
type: string
config:
description: >-
Key of the config backing this value, or null when
the value is not config-backed. The config
supplies the base JSON (and its schema); the value
is an override patch merged on top.
anyOf:
- type: string
- type: 'null'
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
- allOf:
- $ref: '#/components/schemas/FeatureBaseRule'
- type: object
properties:
type:
type: string
const: contextual-bandit-ref
variations:
type: array
items:
type: object
properties:
value:
type: string
variationId:
type: string
config:
description: >-
Key of the config backing this value, or null when
the value is not config-backed. The config
supplies the base JSON (and its schema); the value
is an override patch merged on top.
anyOf:
- type: string
- type: 'null'
required:
- value
- variationId
additionalProperties: false
contextualBanditId:
type: string
required:
- type
- variations
- contextualBanditId
additionalProperties: false
- $ref: '#/components/schemas/FeatureSafeRolloutRule'
title: Feature Safe Rollout Rule
- 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
ConfirmationHeld:
type: object
properties:
confirmation:
$ref: '#/components/schemas/Confirmation'
message:
type: string
required:
- confirmation
- message
additionalProperties: false
$defs:
Confirmation:
id: Confirmation
type: object
properties:
id:
type: string
status:
type: string
enum:
- pending
- running
- completed
- rejected
- expired
actions:
type: array
items:
type: object
properties:
action:
type: string
enum:
- feature.create
- feature.draft
- feature.review
- feature.publish
- feature.archive
- feature.delete
- feature.other
- experiment.create
- experiment.draft
- experiment.start
- experiment.stop
- experiment.targeting
- experiment.traffic
- experiment.phases
- experiment.visualEditor
- experiment.other
- savedGroup.create
- savedGroup.draft
- savedGroup.review
- savedGroup.publish
- savedGroup.archive
- savedGroup.delete
- savedGroup.other
- constant.create
- constant.draft
- constant.review
- constant.publish
- constant.archive
- constant.delete
- constant.other
- config.create
- config.draft
- config.review
- config.publish
- config.archive
- config.delete
- config.other
- rampSchedule.create
- rampSchedule.start
- rampSchedule.pause
- rampSchedule.progression
- rampSchedule.approve
- rampSchedule.edit
- rampSchedule.delete
- rampSchedule.other
- settings.approvals
- settings.other
- access.members
- access.teams
- customHook.create
- customHook.edit
- customHook.delete
- environment.create
- environment.edit
- environment.delete
- project.create
- project.edit
- project.delete
- attribute.create
- attribute.edit
- attribute.delete
- customField.create
- customField.edit
- customField.delete
- sdkConnection.create
- sdkConnection.edit
- sdkConnection.delete
- metric.create
- metric.edit
- metric.delete
- factTable.create
- factTable.edit
- factTable.delete
- segment.create
- segment.edit
- segment.delete
- dimension.create
- dimension.edit
- dimension.delete
- override.ignoreWarnings
- override.skipSchemaValidation
- override.skipHooks
- override.bypassApproval
- override.restBypassesReviews
- override.draftLimit
- override.skipChecklist
- override.bypassDuplicateKeyCheck
- override.unscopedRules
- other.write
environments:
type: array
items:
type: string
required:
- action
- environments
additionalProperties: false
summary:
type: string
url:
type: string
expiresAt:
type: string
response:
anyOf:
- type: object
properties:
status:
type: number
body: {}
required:
- status
- body
additionalProperties: false
- type: 'null'
note:
anyOf:
- type: string
- type: 'null'
required:
- id
- status
- actions
- summary
- url
- expiresAt
- response
- note
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
allProjects:
description: >-
When true (the default) the rule applies to every project the
feature is delivered to. When false the rule is limited to
`projects`.
type: boolean
projects:
description: >-
Project IDs this rule is scoped to when `allProjects` is false.
An empty array scopes the rule to no project.
type: array
items:
type: string
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
allProjects:
description: >-
When true (the default) the rule applies to every project the
feature is delivered to. When false the rule is limited to
`projects`.
type: boolean
projects:
description: >-
Project IDs this rule is scoped to when `allProjects` is false.
An empty array scopes the rule to no project.
type: array
items:
type: string
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
allProjects:
description: >-
When true (the default) the rule applies to every project the
feature is delivered to. When false the rule is limited to
`projects`.
type: boolean
projects:
description: >-
Project IDs this rule is scoped to when `allProjects` is false.
An empty array scopes the rule to no project.
type: array
items:
type: string
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
FeatureBaseRule:
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
allProjects:
description: >-
When true (the default) the rule applies to every project the
feature is delivered to. When false the rule is limited to
`projects`.
type: boolean
projects:
description: >-
Project IDs this rule is scoped to when `allProjects` is false. An
empty array scopes the rule to no project.
type: array
items:
type: string
required:
- description
- id
- enabled
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
allProjects:
description: >-
When true (the default) the rule applies to every project the
feature is delivered to. When false the rule is limited to
`projects`.
type: boolean
projects:
description: >-
Project IDs this rule is scoped to when `allProjects` is false.
An empty array scopes the rule to no project.
type: array
items:
type: string
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
Confirmation:
type: object
properties:
id:
type: string
status:
type: string
enum:
- pending
- running
- completed
- rejected
- expired
actions:
type: array
items:
type: object
properties:
action:
type: string
enum:
- feature.create
- feature.draft
- feature.review
- feature.publish
- feature.archive
- feature.delete
- feature.other
- experiment.create
- experiment.draft
- experiment.start
- experiment.stop
- experiment.targeting
- experiment.traffic
- experiment.phases
- experiment.visualEditor
- experiment.other
- savedGroup.create
- savedGroup.draft
- savedGroup.review
- savedGroup.publish
- savedGroup.archive
- savedGroup.delete
- savedGroup.other
- constant.create
- constant.draft
- constant.review
- constant.publish
- constant.archive
- constant.delete
- constant.other
- config.create
- config.draft
- config.review
- config.publish
- config.archive
- config.delete
- config.other
- rampSchedule.create
- rampSchedule.start
- rampSchedule.pause
- rampSchedule.progression
- rampSchedule.approve
- rampSchedule.edit
- rampSchedule.delete
- rampSchedule.other
- settings.approvals
- settings.other
- access.members
- access.teams
- customHook.create
- customHook.edit
- customHook.delete
- environment.create
- environment.edit
- environment.delete
- project.create
- project.edit
- project.delete
- attribute.create
- attribute.edit
- attribute.delete
- customField.create
- customField.edit
- customField.delete
- sdkConnection.create
- sdkConnection.edit
- sdkConnection.delete
- metric.create
- metric.edit
- metric.delete
- factTable.create
- factTable.edit
- factTable.delete
- segment.create
- segment.edit
- segment.delete
- dimension.create
- dimension.edit
- dimension.delete
- override.ignoreWarnings
- override.skipSchemaValidation
- override.skipHooks
- override.bypassApproval
- override.restBypassesReviews
- override.draftLimit
- override.skipChecklist
- override.bypassDuplicateKeyCheck
- override.unscopedRules
- other.write
environments:
type: array
items:
type: string
required:
- action
- environments
additionalProperties: false
summary:
type: string
url:
type: string
expiresAt:
type: string
response:
anyOf:
- type: object
properties:
status:
type: number
body: {}
required:
- status
- body
additionalProperties: false
- type: 'null'
note:
anyOf:
- type: string
- type: 'null'
required:
- id
- status
- actions
- summary
- url
- expiresAt
- response
- note
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
responses:
ConfirmationHeld:
description: >-
Held until a person confirms it in GrowthBook. Poll the Location until
the confirmation completes.
headers:
Location:
description: The confirmation to poll
schema:
type: string
Retry-After:
description: Seconds to wait before polling
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ConfirmationHeld'
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
```
````