> ## 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.
# Partially update a single config
> Applies the change immediately and records it as a published revision, so it appears in history and fires revision webhooks. When the organization requires approvals, open a draft instead or pass `bypassApproval` with the bypass permission.
## OpenAPI
````yaml openapi.yaml POST /v1/configs/{key}
openapi: 3.1.0
info:
version: 5.0.1
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** - 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. 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
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 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: 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: 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: 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: 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: 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: 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: 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: Team_model
x-displayName: Team
description:
- name: VisualChange_model
x-displayName: Visual Change
description:
- name: VisualChangeset_model
x-displayName: Visual Changeset
description:
paths:
/v1/configs/{key}:
post:
tags:
- configs
summary: Partially update a single config
description: >-
Applies the change immediately and records it as a published revision,
so it appears in history and fires revision webhooks. When the
organization requires approvals, open a draft instead or pass
`bypassApproval` with the bypass permission.
operationId: updateConfig
parameters:
- name: key
in: path
required: true
description: The key of the config
schema:
description: The key of the config
type: string
- $ref: '#/components/parameters/skipSchemaValidation'
- $ref: '#/components/parameters/ignoreWarnings'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
parent:
description: >-
Change the lineage parent (the `key` of the config to
inherit from). Set to an empty string to detach from the
parent and make this a root config.
type: string
extends:
description: >-
Replace the composition bases (mixins) layered on top of
`parent`, in precedence order (later overrides earlier; all
override `parent`; own keys win last). Send the complete
set; an empty array clears all mixins. Set inheritance here,
never via a `@config:` entry in `value`.
type: array
items:
type: string
value:
description: >-
This config's base value as a JSON object.
Per-environment/project variants are expressed via
`scopedOverrides`.
type: object
propertyNames:
type: string
additionalProperties: {}
scopedOverrides:
description: >-
Replace the ordered, first-match-wins
environment/project-scoped variant selection. Each entry
points at a flavor config (a child config, by `key`) whose
value is deep-merged onto this config's resolved value when
the (environment, project) scope matches. Send the complete
list; an empty array clears all overrides; omit to leave
unchanged. Entries must reference existing configs, may not
reference this config itself, and may not be unreachable.
type: array
items:
type: object
properties:
config:
description: >-
The `key` of the flavor config (a child config) whose
value patches this config when the scope matches.
type: string
environments:
description: >-
Environment ids this entry applies to. Empty/omitted =
any environment.
type: array
items:
type: string
projects:
description: >-
Project ids this entry applies to. Empty/omitted = any
project.
type: array
items:
type: string
required:
- config
additionalProperties: false
description:
type: string
maxLength: 10000
project:
type: string
owner:
description: >-
The userId or email address of the owner. If an email
address is provided, it will be used to look up the userId
of the matching organization member. If an ID is provided,
it will be validated as existing in the organization.
type: string
schema:
$ref: '#/components/schemas/ConfigSchemaSource'
description: >-
Replace this config's field definitions, as a JSON Schema
document (`{ type: "json-schema", value }`) or typed-code
source (`{ type: "typescript" | "protobuf" | "python" | "go"
| "rust", value }`). Fields whose key a published ancestor
already owns follow "base wins": an identical re-declaration
is stripped with a `redundant-declaration` warning; one with
a differing definition is rejected. A schema change cascades
the 'base wins' normalization to descendants when published;
a change that removes or retypes fields descendants still
use soft-blocks with a 422 unless the request body sets
`ignoreWarnings: true`. Conversion warnings are returned in
`warnings`.
source:
description: >-
Optional identifier of the consuming codebase/service. When
a `typescript` or `protobuf` schema is supplied, its
named-type structure is captured under this source for
reproduction on export.
type: string
extensible:
type: boolean
experimentGuard:
description: >-
Enable or disable the experiment guard for this Config.
Disabling it requires Bypass draft approvals access.
type: boolean
invariants:
description: >-
Replace the config's cross-field validation rules. Each
rule's expression is a mongo condition (mongrule). Send the
complete set; an empty array clears all rules. Omit to leave
them unchanged.
type: array
items:
type: object
properties:
name:
type: string
maxLength: 128
rule:
description: >-
The rule expression, as a mongo condition (mongrule) —
the same condition syntax as feature targeting,
extended with `{ "$ref": "otherField" }` to compare
against another field, e.g. `{ "min_replicas": {
"$lte": { "$ref": "max_replicas" } } }`.
type: object
propertyNames:
type: string
additionalProperties: {}
message:
description: >-
Shown to editors when the rule is violated. Optional —
defaults to a generic message naming the rule.
type: string
maxLength: 10000
required:
- name
- rule
additionalProperties: false
bypassApproval:
description: >-
Set to true to write directly to the live Config without
approval. The caller must have Bypass draft approvals access
in the Config's Project, unless the organization enables the
REST API approval bypass. This field has no effect when
approval is not required.
type: boolean
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.
type: boolean
skipSchemaValidation:
description: >-
Set to true to publish despite schema validation errors,
failed invariants, or schema changes that invalidate
dependent resources. This does not bypass a rejected Custom
Hook; use `skipHooks` for that. The caller must have Bypass
draft approvals access for Feature Flags, Configs, and
Constants in every Project. Otherwise, this field is
ignored.
type: boolean
skipHooks:
description: >-
Set to true to publish despite a Custom Hook rejection. This
does not bypass schema validation; use
`skipSchemaValidation` for that. The caller must have Bypass
draft approvals access for Feature Flags, Configs, and
Constants in every Project. Otherwise, this field is
ignored.
type: boolean
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
config:
$ref: '#/components/schemas/Config'
warnings:
type: array
items:
$ref: '#/components/schemas/ConfigSchemaWarning'
postPublishWarnings:
description: >-
Steps that failed AFTER the value publish committed (e.g.
an experiment-guard toggle in the same request). The
publish stands; retry only the named step.
type: array
items:
type: string
bypassedGates:
description: >-
Gates that would have blocked this publish but were
bypassed by the caller's authority. Present only when at
least one gate was bypassed.
type: array
items:
$ref: '#/components/schemas/bypassedGates'
required:
- config
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/configs/checkout-flow' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"value":{"timeout":60,"retries":3}}'
components:
parameters:
skipSchemaValidation:
name: skipSchemaValidation
in: query
description: Deprecated — pass `skipSchemaValidation` in the request body instead.
schema:
description: Deprecated — pass `skipSchemaValidation` in the request body instead.
deprecated: true
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
ignoreWarnings:
name: ignoreWarnings
in: query
description: Deprecated — pass `ignoreWarnings` in the request body instead.
schema:
description: Deprecated — pass `ignoreWarnings` in the request body instead.
deprecated: true
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
schemas:
ConfigSchemaSource:
anyOf:
- type: object
properties:
type:
type: string
const: json-schema
value:
description: A JSON Schema document (an object).
type: object
propertyNames:
type: string
additionalProperties: {}
required:
- type
- value
additionalProperties: false
- type: object
properties:
type:
type: string
const: typescript
value:
description: TypeScript source — an interface or object type.
type: string
required:
- type
- value
additionalProperties: false
- type: object
properties:
type:
type: string
const: protobuf
value:
description: Protobuf (proto3) source — a `message` definition.
type: string
required:
- type
- value
additionalProperties: false
- type: object
properties:
type:
type: string
const: python
value:
description: Python source — a Pydantic `BaseModel` class.
type: string
required:
- type
- value
additionalProperties: false
- type: object
properties:
type:
type: string
const: go
value:
description: Go source — a `struct` definition.
type: string
required:
- type
- value
additionalProperties: false
- type: object
properties:
type:
type: string
const: rust
value:
description: Rust source — a serde `struct` definition.
type: string
required:
- type
- value
additionalProperties: false
Config:
type: object
properties:
id:
type: string
key:
description: Stable reference handle; used as `@config:key` in values
type: string
name:
type: string
owner:
description: The userId of the owner (or raw owner name/email for legacy records)
type: string
ownerEmail:
description: >-
The email address of the owner, when the owner can be resolved to a
known user.
type: string
parent:
description: >-
The `key` of the config this one inherits from (lineage parent — the
primary spine). Synthesized into `$extends` at resolution time and
never stored in `value`.
type: string
extends:
description: >-
Additional composition bases (config `key`s) layered on top of
`parent`, in precedence order (later overrides earlier; all override
`parent`; this config's own keys win last). Like `parent`, set via
this field — never via a `@config:` entry in `value`.
type: array
items:
type: string
value:
description: >-
This config's own base value as a JSON object (its declared fields
only — inherited fields are layered in at resolution time, not
stored here). Per-environment/project variants are expressed via
`scopedOverrides`, not here.
type: object
propertyNames:
type: string
additionalProperties: {}
scopedOverrides:
description: >-
Ordered, first-match-wins environment/project-scoped variant
selection. Each entry points at a flavor config (a child config, by
`key`) whose value is deep-merged onto this config's resolved value
when the (environment, project) scope matches — resolved at build
time, per layer. This is how you create an environment-scoped
override (as opposed to a plain child config): make a child config
for the override value, then add it here with its scope. Send the
complete list to replace it; an empty array clears all overrides.
Entries must reference existing configs, may not reference this
config itself, and may not be unreachable (fully subsumed by an
earlier entry).
type: array
items:
type: object
properties:
config:
description: >-
The `key` of the flavor config (a child config) whose value
patches this config when the scope matches.
type: string
environments:
description: >-
Environment ids this entry applies to. Empty/omitted = any
environment.
type: array
items:
type: string
projects:
description: >-
Project ids this entry applies to. Empty/omitted = any
project.
type: array
items:
type: string
required:
- config
additionalProperties: false
scopedConfig:
description: >-
Present ONLY when this config is an environment/project-scoped
override (a "flavor") of another config. Its value is a patch that
applies solely within the listed environments/projects, layered onto
`parent` at resolution — it is NOT a standalone config. A plain
config (including an ordinary child that just inherits from a
`parent`) omits this field entirely. Read-only: create/change the
relationship via the parent config's `scopedOverrides`, never by
setting this directly.
type: object
properties:
parent:
description: The base config this one is a scoped override of.
type: string
environments:
description: >-
Environments this override applies to (empty/absent = every
environment).
type: array
items:
type: string
projects:
description: >-
Projects this override applies to (empty/absent = every
project).
type: array
items:
type: string
required:
- parent
additionalProperties: false
description:
type: string
maxLength: 10000
project:
description: The project this config belongs to (empty = all projects)
type: string
archived:
type: boolean
schema:
description: >-
This config's own field definitions as a JSON Schema document (its
contribution to the family's effective schema). Inherited fields are
owned by ancestors and are not repeated here.
type: object
properties:
type:
type: string
const: json-schema
value:
description: A JSON Schema document (an object).
type: object
propertyNames:
type: string
additionalProperties: {}
required:
- type
- value
additionalProperties: false
extensible:
description: >-
Whether this config family permits extra keys beyond the declared
fields (child configs, feature rules, ad-hoc overrides). Only the
root config's flag applies. Absent = inherit the org default.
type: boolean
invariants:
description: >-
Cross-field validation rules (relational checks JSON Schema can't
express, e.g. implications or comparing two fields), evaluated
against the resolved value at publish.
type: array
items:
type: object
properties:
name:
description: Unique name for the rule.
type: string
maxLength: 128
rule:
description: >-
A mongo condition (mongrule) boolean expression over the
config's fields.
type: object
propertyNames:
type: string
additionalProperties: {}
message:
description: Human-readable error shown when the rule is violated.
type: string
maxLength: 10000
required:
- name
- rule
- message
additionalProperties: false
locked:
description: >-
Whether this Config is locked to a published revision. Drafts can
still be created and edited while locked, but no change can be
published until a user with Bypass draft approvals access unlocks
it.
type: boolean
experimentGuard:
description: >-
Whether the experiment guard is enabled. When enabled, publishing a
value used by a running experiment returns a warning that must be
acknowledged with `ignoreWarnings: true`. Disabling the guard
requires Bypass draft approvals access.
type: boolean
lockedRevision:
description: >-
The pinned published revision (present only when `locked`). Fetch it
via `GET /configs-revisions/:key/:version` for a value guaranteed
not to disappear or mutate — use it to pin reproducible builds.
type: object
properties:
id:
type: string
version:
type: number
required:
- id
- version
additionalProperties: false
lockedBy:
description: Id of the user who locked the config (when `locked`).
type: string
dateLocked:
format: date-time
description: When the config was locked (when `locked`).
type: string
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
required:
- id
- key
- name
- dateCreated
- dateUpdated
additionalProperties: false
ConfigSchemaWarning:
type: object
properties:
code:
type: string
enum:
- dropped-declaration
- non-object-root
- unresolved-type
- unsupported-member
- redundant-declaration
- undeclared-rule-field
message:
type: string
path:
type: string
required:
- code
- message
additionalProperties: false
bypassedGates:
type: object
properties:
type:
description: >-
The gate that was bypassed (e.g. "approval-required", "stale-base",
"schema-break").
type: string
outcome:
type: string
const: bypassed
via:
description: >-
How the gate was bypassed. The value identifies a request field
(`ignoreWarnings`, `skipSchemaValidation`, or `skipHooks`), the
caller's permission (`bypassApprovalPermission`), or an organization
setting (`restApiBypassesReviews`, or `revertsBypassApproval` on a
revert).
type: string
enum:
- ignoreWarnings
- skipSchemaValidation
- skipHooks
- bypassApprovalPermission
- restApiBypassesReviews
- revertsBypassApproval
required:
- type
- outcome
- via
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
```
````