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
- **409** - Conflict - The resource changed since it was read, or its state
blocks the request, such as an experiment start's checklist. `code` names
which.
- **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 and experiment start 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, `skipHooks` for Custom Hook rejections, or
`skipChecklist` for an experiment start's launch checklist items. 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`, `skipChecklist`, `bypassApprovalPermission`,
`restApiBypassesReviews`, or `revertsBypassApproval` (reverts only). This
field is omitted when no gates were bypassed.
### Request flags
Every refusal a request can get past with a flag:
| Flag | Where | Gets
past
|
| ------------------------- | ------------ |
------------------------------------------------------------------------------------------------------------
|
| `ignoreWarnings` | Body | Warnings
(`422`)
|
| `skipSchemaValidation` | Body | Schema and invariant failures,
with **Bypass draft approvals**
access |
| `skipHooks` | Body | Custom Hook
rejections
|
| `skipChecklist` | Body | An experiment start's
incomplete launch checklist items (`409` `checklist_incomplete`), but not
its blockers |
| `allowUnscopedRules` | Body | A rule for All Environments and
All Projects where the organization requires a scope (`422` `unscoped_rule`)
|
| `overrideDraftLimit=true` | Query string | Creating a draft past the draft
limit
|
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)
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: SavedGroupUpload_model
x-displayName: Saved Group Upload
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: >-
security:
- bearerAuth: []
- basicAuth: []
paths:
/v1/features:
get:
operationId: listFeatures
summary: Get all features
description: >
**Deprecated.** Use [GET /v2/features](#operation/listFeaturesV2)
instead.
Returns features with pagination. The skipPagination query parameter is
honored only when API_ALLOW_SKIP_PAGINATION is set (self-hosted
deployments).
deprecated: true
tags:
- features
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/projectId'
- $ref: '#/components/parameters/clientKey'
- $ref: '#/components/parameters/skipPagination'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
features:
type: array
items:
$ref: '#/components/schemas/FeatureV1'
required:
- features
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/features' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postFeature
summary: Create a single feature
description: >-
**Deprecated.** Use [POST /v2/features](#operation/postFeatureV2)
instead.
deprecated: true
tags:
- features
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
pattern: ^[a-zA-Z0-9_.:\|\-]+$
description: >-
Unique, permanent key, shown as the Feature Flag's name in
the UI and used in code. Keep it short. If
`featureRegexValidator` in `GET /api/v1/settings` is set,
follow it (`featureKeyExample` shows the format); otherwise
use kebab-case (e.g. `checkout-express-pay`). Put context in
`description`.
type: string
minLength: 1
archived:
type: boolean
description:
description: >-
Markdown. What the Feature Flag gates and why, rollout plan,
and links. Put context here, not in the key.
type: string
maxLength: 10000
owner:
description: >-
The userId or email address of the owner. If an email
address is provided, it will be used to look up the userId
of the matching organization member. If an ID is provided,
it will be validated as existing in the organization. When
omitted, it defaults to the requesting member: a personal
access token's owner, or the member an organization API key
assumes. An organization API key acting as itself must send
it, or the request fails with a 400.
type: string
project:
description: An associated project ID
type: string
targetingAllProjects:
description: >-
Make this feature discoverable in — and served to — every
project, beyond its primary `project`. Requires the
`targetFeatures` permission (FlagsTarget policy) unscoped to
any project. Governance stays with `project`.
type: boolean
targetingProjects:
description: >-
Secondary project IDs this feature is targeted in and served
to, beyond its primary `project`. Adding a project requires
the `targetFeatures` permission (FlagsTarget policy) in that
project. Governance stays with `project`.
type: array
items:
type: string
valueType:
description: The data type of the feature payload. Boolean by default.
type: string
enum:
- boolean
- string
- number
- json
defaultValue:
description: >-
Default value when feature is enabled. Type must match
`valueType`. In Config mode (`baseConfig` set) this is the
JSON override patch merged on top of the config.
type: string
baseConfig:
description: >-
Key of the config backing this flag ("Config mode").
Requires `valueType: "json"` and a live config;
`defaultValue` and rule values become override patches on
top. null or omitted for a plain flag.
anyOf:
- type: string
- type: 'null'
tags:
description: >-
Tags for filtering and grouping. Use these instead of
encoding groups in names.
type: array
items:
type: string
environments:
description: >-
Settings for each environment, keyed by environment ID. Any
environment you leave out is enabled or disabled per that
environment's "Default state for new features" setting.
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
enabled:
type: boolean
rules:
type: array
items:
anyOf:
- type: object
properties:
allProjects:
description: >-
When true (default), the rule applies to
every project the feature is delivered to.
When false, `projects` scopes it.
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
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
description:
description: >-
Short note on why the rule exists (e.g.
`Beta testers only`).
type: string
maxLength: 10000
condition:
description: Applied to everyone by default.
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted so
a GET response can be posted back unchanged;
`savedGroups` takes precedence if both are
sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: force
value:
type: string
sparse:
description: >-
JSON features only. When true, the rule
value is a partial object merged onto the
feature's default value instead of replacing
it.
type: boolean
required:
- type
- value
additionalProperties: false
- type: object
properties:
allProjects:
description: >-
When true (default), the rule applies to
every project the feature is delivered to.
When false, `projects` scopes it.
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
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
description:
description: >-
Short note on why the rule exists (e.g.
`Beta testers only`).
type: string
maxLength: 10000
condition:
description: Applied to everyone by default.
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted so
a GET response can be posted back unchanged;
`savedGroups` takes precedence if both are
sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: rollout
value:
type: string
sparse:
description: >-
JSON features only. When true, the rule
value is a partial object merged onto the
feature's default value instead of replacing
it.
type: boolean
coverage:
description: >-
Percent of traffic included in this
experiment. Users not included in the
experiment will skip this rule.
type: number
hashAttribute:
type: string
fallbackAttribute:
description: >-
Used in place of `hashAttribute` when a user
lacks it. Only SDKs with Sticky Bucketing
enabled use it.
type: string
seed:
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
- type: object
properties:
allProjects:
description: >-
When true (default), the rule applies to
every project the feature is delivered to.
When false, `projects` scopes it.
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
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
description:
description: >-
Short note on why the rule exists (e.g.
`Beta testers only`).
type: string
maxLength: 10000
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: experiment-ref
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted so
a GET response can be posted back unchanged;
`savedGroups` takes precedence if both are
sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
variations:
type: array
items:
type: object
properties:
value:
type: string
variationId:
type: string
required:
- value
- variationId
additionalProperties: false
experimentId:
type: string
sparse:
description: >-
JSON features only. When true, the rule
value is a partial object merged onto the
feature's default value instead of replacing
it.
type: boolean
required:
- type
- variations
- experimentId
additionalProperties: false
- type: object
properties:
allProjects:
description: >-
When true (default), the rule applies to
every project the feature is delivered to.
When false, `projects` scopes it.
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
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted so
a GET response can be posted back unchanged;
`savedGroups` takes precedence if both are
sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
description:
description: >-
Short note on why the rule exists (e.g.
`Beta testers only`).
type: string
maxLength: 10000
condition:
type: string
id:
type: string
enabled:
description: Enabled by default
type: boolean
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
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
values:
type: array
items:
type: object
properties:
value:
type: string
weight:
type: number
name:
type: string
required:
- value
- weight
additionalProperties: false
value:
deprecated: true
description: >-
Support passing values under the value key
as that was the original spec for
FeatureExperimentRules
type: array
items:
type: object
properties:
value:
type: string
weight:
type: number
name:
type: string
required:
- value
- weight
additionalProperties: false
experimentType:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
hypothesis:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
hashVersion:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
datasource:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
exposureQueryId:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
goalMetrics:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
secondaryMetrics:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
guardrailMetrics:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
activationMetric:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
segment:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
skipPartialData:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
regressionAdjustmentEnabled:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
sequentialTestingEnabled:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
sequentialTestingTuningParameter:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
statsEngine:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
banditStage:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
banditStageDateStarted:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
banditScheduleValue:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
banditScheduleUnit:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
banditBurnInValue:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
banditBurnInUnit:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
banditConversionWindowValue:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
banditConversionWindowUnit:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
templateId:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
customFields:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
required:
- condition
- type
additionalProperties: false
definition:
description: >-
A JSON stringified
[FeatureDefinition](#tag/FeatureDefinition_model)
type: string
draft:
description: Use to write draft changes without publishing them.
type: object
properties:
enabled:
type: boolean
rules:
type: array
items:
anyOf:
- type: object
properties:
allProjects:
description: >-
When true (default), the rule applies to
every project the feature is delivered
to. When false, `projects` scopes it.
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
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
description:
description: >-
Short note on why the rule exists (e.g.
`Beta testers only`).
type: string
maxLength: 10000
condition:
description: Applied to everyone by default.
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted
so a GET response can be posted back
unchanged; `savedGroups` takes
precedence if both are sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: force
value:
type: string
sparse:
description: >-
JSON features only. When true, the rule
value is a partial object merged onto
the feature's default value instead of
replacing it.
type: boolean
required:
- type
- value
additionalProperties: false
- type: object
properties:
allProjects:
description: >-
When true (default), the rule applies to
every project the feature is delivered
to. When false, `projects` scopes it.
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
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
description:
description: >-
Short note on why the rule exists (e.g.
`Beta testers only`).
type: string
maxLength: 10000
condition:
description: Applied to everyone by default.
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted
so a GET response can be posted back
unchanged; `savedGroups` takes
precedence if both are sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: rollout
value:
type: string
sparse:
description: >-
JSON features only. When true, the rule
value is a partial object merged onto
the feature's default value instead of
replacing it.
type: boolean
coverage:
description: >-
Percent of traffic included in this
experiment. Users not included in the
experiment will skip this rule.
type: number
hashAttribute:
type: string
fallbackAttribute:
description: >-
Used in place of `hashAttribute` when a
user lacks it. Only SDKs with Sticky
Bucketing enabled use it.
type: string
seed:
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
- type: object
properties:
allProjects:
description: >-
When true (default), the rule applies to
every project the feature is delivered
to. When false, `projects` scopes it.
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
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
description:
description: >-
Short note on why the rule exists (e.g.
`Beta testers only`).
type: string
maxLength: 10000
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: experiment-ref
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted
so a GET response can be posted back
unchanged; `savedGroups` takes
precedence if both are sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
variations:
type: array
items:
type: object
properties:
value:
type: string
variationId:
type: string
required:
- value
- variationId
additionalProperties: false
experimentId:
type: string
sparse:
description: >-
JSON features only. When true, the rule
value is a partial object merged onto
the feature's default value instead of
replacing it.
type: boolean
required:
- type
- variations
- experimentId
additionalProperties: false
- type: object
properties:
allProjects:
description: >-
When true (default), the rule applies to
every project the feature is delivered
to. When false, `projects` scopes it.
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
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted
so a GET response can be posted back
unchanged; `savedGroups` takes
precedence if both are sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
description:
description: >-
Short note on why the rule exists (e.g.
`Beta testers only`).
type: string
maxLength: 10000
condition:
type: string
id:
type: string
enabled:
description: Enabled by default
type: boolean
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
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
values:
type: array
items:
type: object
properties:
value:
type: string
weight:
type: number
name:
type: string
required:
- value
- weight
additionalProperties: false
value:
deprecated: true
description: >-
Support passing values under the value
key as that was the original spec for
FeatureExperimentRules
type: array
items:
type: object
properties:
value:
type: string
weight:
type: number
name:
type: string
required:
- value
- weight
additionalProperties: false
experimentType:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
hypothesis:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
hashVersion:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
datasource:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
exposureQueryId:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
goalMetrics:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
secondaryMetrics:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
guardrailMetrics:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
activationMetric:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
segment:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
skipPartialData:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
regressionAdjustmentEnabled:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
sequentialTestingEnabled:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
sequentialTestingTuningParameter:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
statsEngine:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
banditStage:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
banditStageDateStarted:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
banditScheduleValue:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
banditScheduleUnit:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
banditBurnInValue:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
banditBurnInUnit:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
banditConversionWindowValue:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
banditConversionWindowUnit:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
templateId:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
customFields:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
required:
- condition
- type
additionalProperties: false
definition:
description: >-
A JSON stringified
[FeatureDefinition](#tag/FeatureDefinition_model)
type: string
required:
- rules
additionalProperties: false
required:
- enabled
- rules
additionalProperties: false
prerequisites:
description: Feature IDs. Each feature must evaluate to `true`
type: array
items:
type: string
jsonSchema:
description: >-
Use JSON schema to validate the payload of a JSON-type
feature value (enterprise only).
type: string
customFields:
type: object
propertyNames:
type: string
additionalProperties:
type: string
comment:
description: >-
Comment to record on the feature's initial revision.
Defaults to an empty comment.
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
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. 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
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. 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:
- id
- valueType
- defaultValue
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
feature:
$ref: '#/components/schemas/FeatureV1'
required:
- feature
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/features' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}:
get:
operationId: getFeature
summary: Get a single feature
description: >-
**Deprecated.** Use [GET /v2/features/:id](#operation/getFeatureV2)
instead.
deprecated: true
tags:
- features
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/withRevisions'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
feature:
$ref: '#/components/schemas/FeatureWithRevisionsV1'
required:
- feature
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/features/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: updateFeature
summary: Partially update a feature
description: >-
**Deprecated.** Use [POST /v2/features/:id](#operation/updateFeatureV2)
instead.
Updates the Feature Flag and immediately publishes a new revision. The
caller needs Edit access in the Feature Flag's Project and Publish
access for every affected environment. When approval is required, use
the revision endpoints instead, unless the caller can bypass draft
approvals.
deprecated: true
tags:
- features
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
description:
description: >-
Markdown. What the Feature Flag gates and why, rollout plan,
and links. Put context here, not in the key.
type: string
maxLength: 10000
archived:
type: boolean
project:
description: An associated project ID
type: string
targetingAllProjects:
description: >-
Make this feature discoverable in — and served to — every
project, beyond its primary `project`. Requires the
`targetFeatures` permission (FlagsTarget policy) unscoped to
any project. Governance stays with `project`.
type: boolean
targetingProjects:
description: >-
Secondary project IDs this feature is targeted in and served
to, beyond its primary `project`. Adding a project requires
the `targetFeatures` permission (FlagsTarget policy) in that
project. Governance stays with `project`.
type: array
items:
type: string
owner:
description: >-
The userId or email address of the owner. If an email
address is provided, it will be used to look up the userId
of the matching organization member. If an ID is provided,
it will be validated as existing in the organization.
type: string
defaultValue:
type: string
baseConfig:
description: >-
The config backing this flag ("Config mode"), fixed at
creation. Cannot be changed by an update — resend the
current value or omit it; a different value (or null to
detach) is rejected.
anyOf:
- type: string
- type: 'null'
tags:
description: >-
Tags for filtering and grouping. Use these instead of
encoding groups in names. Replaces the existing tags
completely.
type: array
items:
type: string
environments:
description: >-
Settings for each environment, keyed by environment ID. Any
environment you leave out keeps its current settings.
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
enabled:
type: boolean
rules:
type: array
items:
anyOf:
- type: object
properties:
allProjects:
description: >-
When true (default), the rule applies to
every project the feature is delivered to.
When false, `projects` scopes it.
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
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
description:
description: >-
Short note on why the rule exists (e.g.
`Beta testers only`).
type: string
maxLength: 10000
condition:
description: Applied to everyone by default.
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted so
a GET response can be posted back unchanged;
`savedGroups` takes precedence if both are
sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: force
value:
type: string
sparse:
description: >-
JSON features only. When true, the rule
value is a partial object merged onto the
feature's default value instead of replacing
it.
type: boolean
required:
- type
- value
additionalProperties: false
- type: object
properties:
allProjects:
description: >-
When true (default), the rule applies to
every project the feature is delivered to.
When false, `projects` scopes it.
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
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
description:
description: >-
Short note on why the rule exists (e.g.
`Beta testers only`).
type: string
maxLength: 10000
condition:
description: Applied to everyone by default.
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted so
a GET response can be posted back unchanged;
`savedGroups` takes precedence if both are
sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: rollout
value:
type: string
sparse:
description: >-
JSON features only. When true, the rule
value is a partial object merged onto the
feature's default value instead of replacing
it.
type: boolean
coverage:
description: >-
Percent of traffic included in this
experiment. Users not included in the
experiment will skip this rule.
type: number
hashAttribute:
type: string
fallbackAttribute:
description: >-
Used in place of `hashAttribute` when a user
lacks it. Only SDKs with Sticky Bucketing
enabled use it.
type: string
seed:
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
- type: object
properties:
allProjects:
description: >-
When true (default), the rule applies to
every project the feature is delivered to.
When false, `projects` scopes it.
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
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
description:
description: >-
Short note on why the rule exists (e.g.
`Beta testers only`).
type: string
maxLength: 10000
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: experiment-ref
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted so
a GET response can be posted back unchanged;
`savedGroups` takes precedence if both are
sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
variations:
type: array
items:
type: object
properties:
value:
type: string
variationId:
type: string
required:
- value
- variationId
additionalProperties: false
experimentId:
type: string
sparse:
description: >-
JSON features only. When true, the rule
value is a partial object merged onto the
feature's default value instead of replacing
it.
type: boolean
required:
- type
- variations
- experimentId
additionalProperties: false
- type: object
properties:
allProjects:
description: >-
When true (default), the rule applies to
every project the feature is delivered to.
When false, `projects` scopes it.
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
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted so
a GET response can be posted back unchanged;
`savedGroups` takes precedence if both are
sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
description:
description: >-
Short note on why the rule exists (e.g.
`Beta testers only`).
type: string
maxLength: 10000
condition:
type: string
id:
type: string
enabled:
description: Enabled by default
type: boolean
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
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
values:
type: array
items:
type: object
properties:
value:
type: string
weight:
type: number
name:
type: string
required:
- value
- weight
additionalProperties: false
value:
deprecated: true
description: >-
Support passing values under the value key
as that was the original spec for
FeatureExperimentRules
type: array
items:
type: object
properties:
value:
type: string
weight:
type: number
name:
type: string
required:
- value
- weight
additionalProperties: false
experimentType:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
hypothesis:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
hashVersion:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
datasource:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
exposureQueryId:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
goalMetrics:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
secondaryMetrics:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
guardrailMetrics:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
activationMetric:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
segment:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
skipPartialData:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
regressionAdjustmentEnabled:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
sequentialTestingEnabled:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
sequentialTestingTuningParameter:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
statsEngine:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
banditStage:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
banditStageDateStarted:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
banditScheduleValue:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
banditScheduleUnit:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
banditBurnInValue:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
banditBurnInUnit:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
banditConversionWindowValue:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
banditConversionWindowUnit:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
templateId:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
customFields:
description: >-
Read-only; ignored on write. Accepted so a
GET response can be posted back unchanged.
required:
- condition
- type
additionalProperties: false
definition:
description: >-
A JSON stringified
[FeatureDefinition](#tag/FeatureDefinition_model)
type: string
draft:
description: Use to write draft changes without publishing them.
type: object
properties:
enabled:
type: boolean
rules:
type: array
items:
anyOf:
- type: object
properties:
allProjects:
description: >-
When true (default), the rule applies to
every project the feature is delivered
to. When false, `projects` scopes it.
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
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
description:
description: >-
Short note on why the rule exists (e.g.
`Beta testers only`).
type: string
maxLength: 10000
condition:
description: Applied to everyone by default.
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted
so a GET response can be posted back
unchanged; `savedGroups` takes
precedence if both are sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: force
value:
type: string
sparse:
description: >-
JSON features only. When true, the rule
value is a partial object merged onto
the feature's default value instead of
replacing it.
type: boolean
required:
- type
- value
additionalProperties: false
- type: object
properties:
allProjects:
description: >-
When true (default), the rule applies to
every project the feature is delivered
to. When false, `projects` scopes it.
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
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
description:
description: >-
Short note on why the rule exists (e.g.
`Beta testers only`).
type: string
maxLength: 10000
condition:
description: Applied to everyone by default.
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted
so a GET response can be posted back
unchanged; `savedGroups` takes
precedence if both are sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: rollout
value:
type: string
sparse:
description: >-
JSON features only. When true, the rule
value is a partial object merged onto
the feature's default value instead of
replacing it.
type: boolean
coverage:
description: >-
Percent of traffic included in this
experiment. Users not included in the
experiment will skip this rule.
type: number
hashAttribute:
type: string
fallbackAttribute:
description: >-
Used in place of `hashAttribute` when a
user lacks it. Only SDKs with Sticky
Bucketing enabled use it.
type: string
seed:
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
- type: object
properties:
allProjects:
description: >-
When true (default), the rule applies to
every project the feature is delivered
to. When false, `projects` scopes it.
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
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
description:
description: >-
Short note on why the rule exists (e.g.
`Beta testers only`).
type: string
maxLength: 10000
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: experiment-ref
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted
so a GET response can be posted back
unchanged; `savedGroups` takes
precedence if both are sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
variations:
type: array
items:
type: object
properties:
value:
type: string
variationId:
type: string
required:
- value
- variationId
additionalProperties: false
experimentId:
type: string
sparse:
description: >-
JSON features only. When true, the rule
value is a partial object merged onto
the feature's default value instead of
replacing it.
type: boolean
required:
- type
- variations
- experimentId
additionalProperties: false
- type: object
properties:
allProjects:
description: >-
When true (default), the rule applies to
every project the feature is delivered
to. When false, `projects` scopes it.
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
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted
so a GET response can be posted back
unchanged; `savedGroups` takes
precedence if both are sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
description:
description: >-
Short note on why the rule exists (e.g.
`Beta testers only`).
type: string
maxLength: 10000
condition:
type: string
id:
type: string
enabled:
description: Enabled by default
type: boolean
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
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
values:
type: array
items:
type: object
properties:
value:
type: string
weight:
type: number
name:
type: string
required:
- value
- weight
additionalProperties: false
value:
deprecated: true
description: >-
Support passing values under the value
key as that was the original spec for
FeatureExperimentRules
type: array
items:
type: object
properties:
value:
type: string
weight:
type: number
name:
type: string
required:
- value
- weight
additionalProperties: false
experimentType:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
hypothesis:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
hashVersion:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
datasource:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
exposureQueryId:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
goalMetrics:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
secondaryMetrics:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
guardrailMetrics:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
activationMetric:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
segment:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
skipPartialData:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
regressionAdjustmentEnabled:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
sequentialTestingEnabled:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
sequentialTestingTuningParameter:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
statsEngine:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
banditStage:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
banditStageDateStarted:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
banditScheduleValue:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
banditScheduleUnit:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
banditBurnInValue:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
banditBurnInUnit:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
banditConversionWindowValue:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
banditConversionWindowUnit:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
templateId:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
customFields:
description: >-
Read-only; ignored on write. Accepted so
a GET response can be posted back
unchanged.
required:
- condition
- type
additionalProperties: false
definition:
description: >-
A JSON stringified
[FeatureDefinition](#tag/FeatureDefinition_model)
type: string
required:
- rules
additionalProperties: false
required:
- enabled
- rules
additionalProperties: false
prerequisites:
description: Feature IDs. Each feature must evaluate to `true`
type: array
items:
type: string
jsonSchema:
description: >-
Use JSON schema to validate the payload of a JSON-type
feature value (enterprise only).
type: string
customFields:
type: object
propertyNames:
type: string
additionalProperties:
type: string
holdout:
description: >
Holdout to assign this feature to. Pass `null` to remove the
feature from its current holdout. Omit the field entirely to
leave the holdout unchanged.
anyOf:
- type: object
properties:
id:
description: Holdout ID
type: string
value:
description: >-
The feature value assigned to users in the holdout
treatment group
type: string
required:
- id
- value
additionalProperties: false
- type: 'null'
comment:
description: >-
Comment to record on the revision this update publishes,
when it publishes one. Defaults to "Created via REST API".
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
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. 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
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. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
feature:
$ref: '#/components/schemas/FeatureV1'
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:
- feature
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/features/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteFeature
summary: Deletes a single feature
description: >-
**Deprecated.** Use [DELETE
/v2/features/:id](#operation/deleteFeatureV2) instead.
Permanently deletes a Feature Flag and all of its revisions. The caller
needs Archive & delete access. Deleting a live Feature Flag also
requires Publish access for every environment where it is enabled and
the organization setting "REST API always bypasses approval
requirements". Otherwise, archive the Feature Flag before deleting it.
deprecated: true
tags:
- features
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
description: The ID of the deleted feature
example: feature-123
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X DELETE 'https://api.growthbook.io/api/v1/features/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/toggle:
post:
operationId: toggleFeature
summary: Toggle a feature in one or more environments
description: >-
**Deprecated.** Use [POST
/v2/features/:id/toggle](#operation/toggleFeatureV2) instead.
Enables or disables a Feature Flag in one or more environments and
immediately publishes the change. The caller needs Publish access for
every environment in the request. When approval is required, use a draft
revision instead, unless the caller can bypass draft approvals.
deprecated: true
tags:
- features
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
reason:
type: string
comment:
description: >-
Comment to record on the revision this toggle publishes,
when it changes any environment. Defaults to "Created via
REST API". (`reason` is recorded in the audit log only.)
type: string
environments:
type: object
propertyNames:
type: string
additionalProperties:
anyOf:
- type: boolean
const: true
- type: boolean
const: false
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '1'
- type: string
const: '0'
- type: number
const: 1
- type: number
const: 0
- type: string
const: ''
required:
- environments
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
feature:
$ref: '#/components/schemas/FeatureV1'
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:
- feature
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST 'https://api.growthbook.io/api/v1/features/{id}/toggle'
\
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"reason":"Kill switch activated","environments":{"production":false}}'
/v1/features/{id}/revert:
post:
operationId: revertFeature
summary: Revert a feature to a specific revision
description: >-
**Deprecated.** Use [POST
/v2/features/:id/revert](#operation/revertFeatureV2) instead.
Restores a previously published revision and immediately publishes the
result as a new revision. The caller needs Revert access for every
affected environment. When approval is required, the request is allowed
only if the caller holds the `FlagsBypassApprovals` policy, or the
organization enables either "REST API always bypasses approval
requirements" or "Allow reverts without approval".
If the restored values no longer match the Feature Flag's current value
type or JSON schema, or restoring an archived state would archive a flag
that live flags or experiments still depend on, the API returns 422 with
`warnings`. Send `"ignoreWarnings": true` to acknowledge those warnings
and continue.
deprecated: true
tags:
- features
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
revision:
type: number
comment:
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
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. 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
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. 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:
- revision
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
feature:
$ref: '#/components/schemas/FeatureV1'
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:
- feature
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST 'https://api.growthbook.io/api/v1/features/{id}/revert'
\
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"revision":3,"comment":"Bug found"}'
/v1/feature-keys:
get:
operationId: getFeatureKeys
summary: Get list of feature keys
description: >-
**Deprecated.** Use [GET /v2/feature-keys](#operation/getFeatureKeysV2)
instead.
deprecated: true
tags:
- features
parameters:
- $ref: '#/components/parameters/projectId'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
type: string
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/feature-keys' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/stale-features:
get:
operationId: getFeatureStale
summary: Get stale status for one or more features
description: >-
**Deprecated.** Use [GET
/v2/stale-features](#operation/getFeatureStaleV2) instead.
deprecated: true
tags:
- features
parameters:
- $ref: '#/components/parameters/ids'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
features:
$ref: '#/components/schemas/features'
required:
- features
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/stale-features' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/revisions:
get:
operationId: listRevisions
summary: List feature revisions
description: >-
**Deprecated.** Use [GET
/v2/feature-revisions](#operation/listRevisionsV2) instead.
Returns a paginated list of feature revisions across all features in the
organization. Optionally filtered by feature, status, author, and/or the
calling user's involvement. Results are sorted newest-first.
deprecated: true
tags:
- feature-revisions
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/skipPagination'
- $ref: '#/components/parameters/featureId'
- $ref: '#/components/parameters/status'
- $ref: '#/components/parameters/author'
- $ref: '#/components/parameters/mine'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revisions:
type: array
items:
$ref: '#/components/schemas/FeatureRevisionV1'
limit:
type: integer
offset:
type: integer
count:
type: integer
total:
type: integer
hasMore:
type: boolean
nextOffset:
anyOf:
- type: integer
- type: 'null'
required:
- revisions
- limit
- offset
- count
- total
- hasMore
- nextOffset
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/revisions' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions:
get:
operationId: getFeatureRevisions
summary: List revisions for a feature
description: >-
**Deprecated.** Use [GET
/v2/features/:id/revisions](#operation/getFeatureRevisionsV2) instead.
Returns a paginated list of revisions for this feature, sorted
newest-first. Optionally filtered by status and/or author.
deprecated: true
tags:
- feature-revisions
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/skipPagination'
- $ref: '#/components/parameters/status'
- $ref: '#/components/parameters/author'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revisions:
type: array
items:
$ref: '#/components/schemas/FeatureRevisionV1'
limit:
type: integer
offset:
type: integer
count:
type: integer
total:
type: integer
hasMore:
type: boolean
nextOffset:
anyOf:
- type: integer
- type: 'null'
required:
- revisions
- limit
- offset
- count
- total
- hasMore
- nextOffset
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/features/abc123/revisions' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postFeatureRevision
summary: Create a draft revision
description: >-
**Deprecated.** Use [POST
/v2/features/:id/revisions](#operation/postFeatureRevisionV2) instead.
Creates a new draft revision branched from the current live revision. A
feature can have multiple concurrent drafts; use this to start an
isolated line of edits.
deprecated: true
tags:
- feature-revisions
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/overrideDraftLimit'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
comment:
type: string
title:
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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/features/{id}/revisions' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions/latest:
get:
operationId: getFeatureRevisionLatest
summary: Get the most recent active draft revision
description: >-
**Deprecated.** Use [GET
/v2/features/:id/revisions/latest](#operation/getFeatureRevisionLatestV2)
instead.
Returns the most recently updated draft revision for the feature.
Returns 404 if there is no active draft. Pass `mine=true` to return the
most recent draft authored by or contributed to by the calling user.
Needs a personal access token, or an organization API key that assumes a
named member's role.
deprecated: true
tags:
- feature-revisions
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- name: mine
in: query
description: >-
If true, return only the most recent active draft authored by or
contributed to by the calling user. Needs a personal access token,
or an organization API key that assumes a named member's role.
schema:
description: >-
If true, return only the most recent active draft authored by or
contributed to by the calling user. Needs a personal access token,
or an organization API key that assumes a named member's role.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/features/{id}/revisions/latest' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions/{version}:
get:
operationId: getFeatureRevision
summary: Get a single feature revision
description: >-
**Deprecated.** Use [GET
/v2/features/:id/revisions/:version](#operation/getFeatureRevisionV2)
instead.
Returns the revision at the specified version for this feature. Use `GET
/features/{id}/revisions/latest` for the most recent active draft.
deprecated: true
tags:
- feature-revisions
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions/{version}/metadata:
put:
operationId: putFeatureRevisionMetadata
summary: Update revision metadata (comment, title, feature metadata)
description: >-
**Deprecated.** Use [PUT
/v2/features/:id/revisions/:version/metadata](#operation/putFeatureRevisionMetadataV2)
instead.
Updates draft-level metadata (`comment`, `title`) and/or feature-level
metadata (owner, project, tags, customFields, jsonSchema, etc.). Merge
semantics: omitted fields are left unchanged; any provided field
replaces the current value (pass an empty string/array/object to clear).
Feature metadata changes are staged on the revision and applied to the
feature on publish. Changing `project` requires publish permission on
both the old and new project.
deprecated: true
tags:
- feature-revisions
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:
comment:
type: string
title:
type: string
description:
type: string
owner:
description: >-
The userId or email address of the owner. If an email
address is provided, it will be used to look up the userId
of the matching organization member. If an ID is provided,
it will be validated as existing in the organization.
type: string
project:
type: string
targetingAllProjects:
description: >-
Stage delivering this feature to every project. Requires the
`targetFeatures` permission unscoped to any project.
type: boolean
targetingProjects:
description: >-
Stage the secondary project IDs this feature is delivered
to. Adding a project requires the `targetFeatures`
permission (FlagsTarget policy) in that project.
type: array
items:
type: string
tags:
type: array
items:
type: string
neverStale:
type: boolean
customFields:
type: object
propertyNames:
type: string
additionalProperties: {}
jsonSchema:
description: >-
Validation schema to stage on the draft. The server sets
`date`, so don't send it.
type: object
properties:
schemaType:
type: string
enum:
- schema
- simple
schema:
type: string
simple:
type: object
properties:
type:
type: string
enum:
- object
- object[]
- primitive
- primitive[]
fields:
type: array
items:
type: object
properties:
key:
type: string
maxLength: 64
type:
type: string
enum:
- integer
- float
- string
- boolean
required:
type: boolean
default:
type: string
maxLength: 256
description:
type: string
maxLength: 10000
enum:
maxItems: 256
type: array
items:
type: string
maxLength: 256
min:
type: number
max:
type: number
nullable:
type: boolean
jsonSchema:
type: string
required:
- key
- type
- required
- default
- description
- enum
additionalProperties: false
additionalProperties:
type: boolean
invariants:
type: array
items:
type: object
properties:
name:
type: string
maxLength: 128
rule:
type: string
message:
type: string
maxLength: 10000
required:
- name
- rule
- message
additionalProperties: false
required:
- type
- fields
additionalProperties: false
enabled:
type: boolean
required:
- schemaType
- schema
- simple
- enabled
additionalProperties: false
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
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/metadata'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions/{version}/default-value:
put:
operationId: putFeatureRevisionDefaultValue
summary: Set the default value in a draft revision
description: >-
**Deprecated.** Use [PUT
/v2/features/:id/revisions/:version/default-value](#operation/putFeatureRevisionDefaultValueV2)
instead.
Replaces the feature's default value for this revision. The value must
be a string representation matching the feature's value type (e.g.
`"true"` for booleans, `42` for numbers, a JSON string for JSON
features).
deprecated: true
tags:
- feature-revisions
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:
defaultValue:
type: string
revisionTitle:
type: string
revisionComment:
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
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. 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
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. 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:
- defaultValue
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/default-value'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions/{version}/prerequisites:
put:
operationId: putFeatureRevisionPrerequisites
summary: Set feature-level prerequisites in a draft revision
description: >-
**Deprecated.** Use [PUT
/v2/features/:id/revisions/:version/prerequisites](#operation/putFeatureRevisionPrerequisitesV2)
instead.
Replaces the feature's prerequisite list for this revision. Each
prerequisite condition is evaluated against `{ value:
}` at SDK eval time — use `value` as the condition
key.
deprecated: true
tags:
- feature-revisions
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:
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
revisionTitle:
type: string
revisionComment:
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:
- prerequisites
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/prerequisites'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions/{version}/holdout:
put:
operationId: putFeatureRevisionHoldout
summary: Set holdout in a draft revision
description: >-
**Deprecated.** Use [PUT
/v2/features/:id/revisions/:version/holdout](#operation/putFeatureRevisionHoldoutV2)
instead.
Sets (or clears, via `holdout: null`) the holdout experiment bound to
the feature. Holdout linkage side-effects (updating the holdout's linked
feature list) are applied on publish.
deprecated: true
tags:
- feature-revisions
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:
holdout:
anyOf:
- type: object
properties:
id:
type: string
value:
type: string
required:
- id
- value
additionalProperties: false
- type: 'null'
revisionTitle:
type: string
revisionComment:
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:
- holdout
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/holdout'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions/{version}/archive:
put:
operationId: putFeatureRevisionArchive
summary: Set archived state in a draft revision
description: >-
**Deprecated.** Use [PUT
/v2/features/:id/revisions/:version/archive](#operation/putFeatureRevisionArchiveV2)
instead.
Sets whether the feature is archived. Archived features are excluded
from SDK payloads on publish.
deprecated: true
tags:
- feature-revisions
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:
type: string
revisionComment:
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/FeatureRevisionV1'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/archive'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions/{version}/toggle:
post:
operationId: postFeatureRevisionToggle
summary: Toggle an environment on/off in a draft revision
description: >-
**Deprecated.** Use [POST
/v2/features/:id/revisions/:version/toggle](#operation/postFeatureRevisionToggleV2)
instead.
Sets whether the feature is enabled in the given environment as part of
the draft. Takes effect on publish.
deprecated: true
tags:
- feature-revisions
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:
environment:
type: string
enabled:
type: boolean
revisionTitle:
type: string
revisionComment:
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:
- environment
- enabled
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/toggle'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions/{version}/rules:
post:
operationId: postFeatureRevisionRuleAdd
summary: Add a rule to a draft revision
description: >-
**Deprecated.** Use [POST
/v2/features/:id/revisions/:version/rules](#operation/postFeatureRevisionRuleAddV2)
instead, which accepts rules with unified
`allEnvironments`/`environments` scope fields instead of a
per-environment `environment` parameter.
Appends a new rule to the end of the rule list for the given
environment. A `rule.type` of `force`, `rollout`, `experiment-ref`, or
`safe-rollout` determines the accepted shape. Use `rampSchedule` for
ramp configuration or `schedule` for a simple start/end window; if both
are provided, `rampSchedule` wins.
deprecated: true
tags:
- feature-revisions
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:
environment:
type: string
rule:
anyOf:
- type: object
properties:
description:
description: >-
Short note on why the rule exists (e.g. `Beta
testers only`).
type: string
enabled:
type: boolean
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
anyOf:
- type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
scheduleType:
type: string
enum:
- none
- schedule
- ramp
type:
type: string
const: experiment-ref
experimentId:
type: string
variations:
type: array
items:
type: object
properties:
variationId:
type: string
value:
type: string
required:
- value
additionalProperties: false
sparse:
type: boolean
required:
- type
- experimentId
- variations
additionalProperties: false
- type: object
properties:
description:
description: >-
Short note on why the rule exists (e.g. `Beta
testers only`).
type: string
enabled:
type: boolean
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
anyOf:
- type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
scheduleType:
type: string
enum:
- none
- schedule
- ramp
type:
type: string
const: safe-rollout
controlValue:
type: string
variationValue:
type: string
hashAttribute:
type: string
trackingKey:
type: string
seed:
type: string
safeRolloutFields:
type: object
properties:
datasourceId:
type: string
exposureQuery:
description: >-
The assignment query, grouping its ID with the
identifier type analyzed on. Mutually exclusive
with the deprecated `exposureQueryId`.
type: object
properties:
id:
description: >-
The ID of one of the data source's
assignment queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the
query must declare. Required when selecting
a different assignment query that declares
several. Otherwise defaults to the current
identifier type, or the query's only one.
Null is treated as omitted, so a response's
value can be sent back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
exposureQueryId:
deprecated: true
description: >-
Deprecated: use `exposureQuery`. Rejected when
selecting a different assignment query that
declares several identifier types; set
`exposureQuery.identifierType` instead.
type: string
guardrailMetricIds:
minItems: 1
type: array
items:
type: string
maxDuration:
type: object
properties:
amount:
type: number
exclusiveMinimum: 0
unit:
type: string
enum:
- weeks
- days
- hours
- minutes
required:
- amount
- unit
additionalProperties: false
autoRollback:
type: boolean
rampUpSchedule:
type: object
properties:
enabled:
type: boolean
steps:
minItems: 1
type: array
items:
type: object
properties:
percent:
type: number
minimum: 0
maximum: 1
required:
- percent
additionalProperties: false
required:
- enabled
additionalProperties: false
required:
- datasourceId
- guardrailMetricIds
- maxDuration
additionalProperties: false
required:
- type
- controlValue
- variationValue
- hashAttribute
- safeRolloutFields
additionalProperties: false
- type: object
properties:
description:
description: >-
Short note on why the rule exists (e.g. `Beta
testers only`).
type: string
enabled:
type: boolean
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
anyOf:
- type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
scheduleType:
type: string
enum:
- none
- schedule
- ramp
type:
type: string
enum:
- force
- rollout
value:
type: string
sparse:
type: boolean
coverage:
type: number
minimum: 0
maximum: 1
hashAttribute:
type: string
fallbackAttribute:
type: string
seed:
type: string
hashVersion:
anyOf:
- type: number
const: 1
- type: number
const: 2
required:
- value
additionalProperties: false
rampSchedule:
type: object
properties:
name:
type: string
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:
- type: string
format: date-time
- type: 'null'
cutoffDate:
description: >-
ISO 8601 date-time, e.g. "2025-07-01T00:00:00Z". The
ramp ends at this time.
anyOf:
- type: string
format: date-time
- type: 'null'
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. Mutually exclusive with
the deprecated `exposureQueryId`.
type: object
properties:
id:
description: >-
The ID of one of the data source's assignment
queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the
query must declare. Required when selecting a
different assignment query that declares
several. Otherwise defaults to the current
identifier type, or the query's only one. Null
is treated as omitted, so a response's value can
be sent back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
exposureQueryId:
deprecated: true
description: >-
Deprecated: use `exposureQuery`. Rejected when
selecting a different assignment query that declares
several identifier types; set
`exposureQuery.identifierType` instead.
type: string
required:
- datasourceId
- guardrailMetricIds
additionalProperties: false
lockdownConfig:
type: object
properties:
mode:
type: string
enum:
- none
- locked
required:
- mode
additionalProperties: false
requiresStartApproval:
anyOf:
- type: boolean
- type: 'null'
additionalProperties: false
schedule:
type: object
properties:
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
additionalProperties: false
revisionTitle:
type: string
revisionComment:
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
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. 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
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. 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:
- environment
- rule
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/rules'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions/{version}/rules/{ruleId}:
put:
operationId: putFeatureRevisionRule
summary: Update a rule in a draft revision
description: >-
**Deprecated.** Use [PUT
/v2/features/:id/revisions/:version/rules/:ruleId](#operation/putFeatureRevisionRuleV2)
instead, which locates rules by `ruleId` in the flat array without an
`environment` parameter.
Patches fields on an existing rule. The rule `type` cannot be changed —
to convert types, delete and re-add. Fields that don't apply to the
current rule type are rejected.
deprecated: true
tags:
- feature-revisions
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
- $ref: '#/components/parameters/ruleId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
environment:
type: string
rule:
type: object
properties:
description:
description: >-
Short note on why the rule exists (e.g. `Beta testers
only`).
type: string
enabled:
type: boolean
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
anyOf:
- type: array
items:
type: object
properties:
timestamp:
anyOf:
- type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
- type: 'null'
scheduleType:
anyOf:
- type: string
enum:
- none
- schedule
- ramp
- type: 'null'
type:
type: string
enum:
- force
- rollout
- experiment-ref
- safe-rollout
value:
type: string
sparse:
type: boolean
coverage:
type: number
minimum: 0
maximum: 1
hashAttribute:
type: string
fallbackAttribute:
type: string
seed:
type: string
hashVersion:
anyOf:
- type: number
const: 1
- type: number
const: 2
experimentId:
type: string
variations:
type: array
items:
type: object
properties:
variationId:
type: string
value:
type: string
required:
- variationId
- value
additionalProperties: false
controlValue:
type: string
variationValue:
type: string
additionalProperties: false
rampSchedule:
type: object
properties:
name:
type: string
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:
- type: string
format: date-time
- type: 'null'
cutoffDate:
description: >-
ISO 8601 date-time, e.g. "2025-07-01T00:00:00Z". The
ramp ends at this time.
anyOf:
- type: string
format: date-time
- type: 'null'
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. Mutually exclusive with
the deprecated `exposureQueryId`.
type: object
properties:
id:
description: >-
The ID of one of the data source's assignment
queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the
query must declare. Required when selecting a
different assignment query that declares
several. Otherwise defaults to the current
identifier type, or the query's only one. Null
is treated as omitted, so a response's value can
be sent back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
exposureQueryId:
deprecated: true
description: >-
Deprecated: use `exposureQuery`. Rejected when
selecting a different assignment query that declares
several identifier types; set
`exposureQuery.identifierType` instead.
type: string
required:
- datasourceId
- guardrailMetricIds
additionalProperties: false
lockdownConfig:
type: object
properties:
mode:
type: string
enum:
- none
- locked
required:
- mode
additionalProperties: false
requiresStartApproval:
anyOf:
- type: boolean
- type: 'null'
additionalProperties: false
schedule:
type: object
properties:
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
additionalProperties: false
revisionTitle:
type: string
revisionComment:
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
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. 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
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. 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:
- environment
- rule
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/rules/{ruleId}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteFeatureRevisionRule
summary: Delete a rule from a draft revision
description: >-
**Deprecated.** Use [DELETE
/v2/features/:id/revisions/:version/rules/:ruleId](#operation/deleteFeatureRevisionRuleV2)
instead, which removes the rule from the flat array without an
`environment` parameter.
Removes the rule from the specified environment. Any pending ramp
actions on the draft for this rule are also cleared.
deprecated: true
tags:
- feature-revisions
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
- $ref: '#/components/parameters/ruleId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
environment:
type: string
revisionTitle:
type: string
revisionComment:
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:
- environment
additionalProperties: false
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/rules/{ruleId}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions/{version}/rules/reorder:
post:
operationId: postFeatureRevisionRulesReorder
summary: Reorder rules in an environment
description: >-
**Deprecated.** Use [POST
/v2/features/:id/revisions/:version/rules/reorder](#operation/postFeatureRevisionRulesReorderV2)
instead, which reorders the global flat rule array without an
`environment` parameter.
Replaces the rule order for the environment. `ruleIds` must contain
**exactly** the set of existing rule IDs in that environment — no
additions, omissions, or duplicates.
deprecated: true
tags:
- feature-revisions
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:
environment:
type: string
ruleIds:
type: array
items:
type: string
revisionTitle:
type: string
revisionComment:
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:
- environment
- ruleIds
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/rules/reorder'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions/{version}/rules/{ruleId}/ramp-schedule:
put:
operationId: putFeatureRevisionRuleRampSchedule
summary: Set ramp schedule for a rule
description: >-
**Deprecated.** Use [PUT
/v2/features/:id/revisions/:version/rules/:ruleId/ramp-schedule](#operation/putFeatureRevisionRuleRampScheduleV2)
instead.
Queues a revision-controlled ramp action for this rule. If the rule
already has a live ramp schedule, this stores an `update` action applied
on publish; otherwise it stores a `create` action. No live schedule
config changes are applied immediately by this endpoint.
deprecated: true
tags:
- feature-revisions
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
- $ref: '#/components/parameters/ruleId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
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:
- type: string
format: date-time
- type: 'null'
cutoffDate:
description: >-
ISO 8601 date-time, e.g. "2025-07-01T00:00:00Z". The ramp
ends at this time.
anyOf:
- type: string
format: date-time
- type: 'null'
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. Mutually exclusive with the
deprecated `exposureQueryId`.
type: object
properties:
id:
description: >-
The ID of one of the data source's assignment
queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the query
must declare. Required when selecting a different
assignment query that declares several. Otherwise
defaults to the current identifier type, or the
query's only one. Null is treated as omitted, so a
response's value can be sent back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
exposureQueryId:
deprecated: true
description: >-
Deprecated: use `exposureQuery`. Rejected when selecting
a different assignment query that declares several
identifier types; set `exposureQuery.identifierType`
instead.
type: string
required:
- datasourceId
- guardrailMetricIds
additionalProperties: false
lockdownConfig:
type: object
properties:
mode:
type: string
enum:
- none
- locked
required:
- mode
additionalProperties: false
requiresStartApproval:
anyOf:
- type: boolean
- type: 'null'
environment:
deprecated: true
type: string
revisionTitle:
type: string
revisionComment:
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
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
warnings:
description: >-
Non-fatal advisories about how the request was
interpreted.
type: array
items:
type: string
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/rules/{ruleId}/ramp-schedule'
\
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteFeatureRevisionRuleRampSchedule
summary: Remove ramp schedule from a rule
description: >-
**Deprecated.** Use [DELETE
/v2/features/:id/revisions/:version/rules/:ruleId/ramp-schedule](#operation/deleteFeatureRevisionRuleRampScheduleV2)
instead.
Removes a pending ramp schedule attached by the draft. If the rule
currently has a live ramp schedule, a detach action is queued and
applied at publish time.
deprecated: true
tags:
- feature-revisions
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
- $ref: '#/components/parameters/ruleId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
environment:
deprecated: true
type: string
revisionTitle:
type: string
revisionComment:
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
additionalProperties: false
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/rules/{ruleId}/ramp-schedule'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions/{version}/request-review:
post:
operationId: postFeatureRevisionRequestReview
summary: Request review for a draft revision
description: >-
**Deprecated.** Use [POST
/v2/features/:id/revisions/:version/request-review](#operation/postFeatureRevisionRequestReviewV2)
instead.
Moves the draft into the `pending-review` state and notifies reviewers.
deprecated: true
tags:
- feature-revisions
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
comment:
type: string
autoPublishOnApproval:
type: boolean
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/request-review'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions/{version}/submit-review:
post:
operationId: postFeatureRevisionSubmitReview
summary: Submit a review on a draft revision
description: >-
**Deprecated.** Use [POST
/v2/features/:id/revisions/:version/submit-review](#operation/postFeatureRevisionSubmitReviewV2)
instead.
Submits an `approve`, `request-changes`, or `comment` review on the
draft. The verdict belongs to whoever the request acts as; see [Naming
who asked](/api/introduction#naming-who-asked). No one can rule on a
draft they created. Contributors cannot approve their own drafts, but
may submit comments or request changes.
When `action` is `approve` and the revision has `autoPublishOnApproval`
enabled, the revision is automatically published after approval. Pass
`skipAutoPublish: true` to approve without triggering auto-publish.
deprecated: true
tags:
- feature-revisions
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
comment:
type: string
action:
description: >-
`approve`, `request-changes` or `comment`. Defaults to
`comment`, which doesn't change whether the draft is
approved.
type: string
enum:
- approve
- request-changes
- comment
skipAutoPublish:
type: boolean
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
autoPublished:
type: boolean
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/submit-review'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions/{version}/merge-status:
get:
operationId: getFeatureRevisionMergeStatus
summary: Get merge status for a draft revision
description: >-
**Deprecated.** Use [GET
/v2/features/:id/revisions/:version/merge-status](#operation/getFeatureRevisionMergeStatusV2)
instead.
Runs a dry-run merge of the draft against the current live revision and
returns any conflicts. Use this before publishing to preview changes and
detect conflicting edits.
deprecated: true
tags:
- feature-revisions
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
liveVersion:
description: The current live version the merge was computed against.
type: number
draftDateUpdated:
format: date-time
description: The draft's last-modified timestamp at merge time.
type: string
conflicts:
type: array
items:
$ref: '#/components/schemas/conflicts'
rebaseRequired:
description: >-
Whether the draft must be rebased before it can be
published. This is true when the merge has conflicts, or
when the organization requires rebasing and the draft or
its approval is out of date. If there are no conflicts, a
caller with Bypass draft approvals access can send
`ignoreWarnings: true` to force-publish instead.
type: boolean
result:
$ref: '#/components/schemas/result'
required:
- success
- liveVersion
- draftDateUpdated
- conflicts
- rebaseRequired
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/merge-status'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions/{version}/rebase:
post:
operationId: postFeatureRevisionRebase
summary: Rebase a draft revision onto the current live version
description: >-
**Deprecated.** Use [POST
/v2/features/:id/revisions/:version/rebase](#operation/postFeatureRevisionRebaseV2)
instead.
Updates the draft's base revision to match the currently-live revision,
applying the draft's changes on top. Supply `conflictResolutions` to
resolve any conflicting fields.
**Conflict key format changed for v1 clients.** The per-rule
`envName.ruleId` keys used by older clients are no longer recognized.
Valid keys: `defaultValue`, `prerequisites`, `archived`, `holdout`,
`environmentsEnabled.`, `metadata.`, `rules.`,
`rules.order`, and the blanket `rules` (applies one strategy to all
rule-level conflicts). Unrecognized keys are ignored; unresolved
conflicts respond with `409`.
deprecated: true
tags:
- feature-revisions
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
conflictResolutions:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- overwrite
- discard
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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/rebase'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions/{version}/publish:
post:
operationId: postFeatureRevisionPublish
summary: Publish a draft revision
description: >-
**Deprecated.** Use [POST
/v2/features/:id/revisions/:version/publish](#operation/postFeatureRevisionPublishV2)
instead.
Publishes the draft and makes its changes live. The caller needs Publish
access for every affected environment. When approval is required, the
draft must be approved unless the caller has Bypass draft approvals
access.
deprecated: true
tags:
- feature-revisions
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
comment:
type: string
bypassApproval:
description: >-
Deprecated and ignored. Approval is bypassed automatically
when the caller has Bypass draft approvals access for this
resource or when the organization enables the REST API
approval bypass. Otherwise, the revision must be approved
before it can be published.
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. 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
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. 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
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. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
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:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/publish'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions/{version}/discard:
post:
operationId: postFeatureRevisionDiscard
summary: Discard a draft revision
description: >-
**Deprecated.** Use [POST
/v2/features/:id/revisions/:version/discard](#operation/postFeatureRevisionDiscardV2)
instead.
Permanently discards a draft revision. Only drafts (never published
revisions) can be discarded. Any pending ramp actions staged on the
draft are dropped.
deprecated: true
tags:
- feature-revisions
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/discard'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/features/{id}/revisions/{version}/revert:
post:
operationId: postFeatureRevisionRevert
summary: Revert the feature to a prior revision
description: >-
**Deprecated.** Use [POST
/v2/features/:id/revisions/:version/revert](#operation/postFeatureRevisionRevertV2)
instead.
Creates a new draft (or immediately publishes) whose content matches the
specified historical revision.
deprecated: true
tags:
- feature-revisions
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
strategy:
type: string
enum:
- draft
- publish
comment:
type: string
title:
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
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. 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
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. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV1'
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:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/revert'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features:
get:
operationId: listFeaturesV2
summary: Get all features
description: >
Returns features with pagination. Rules are returned as a unified
top-level array with per-rule environment scope.
tags:
- features-v2
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/projectId'
- $ref: '#/components/parameters/clientKey'
- $ref: '#/components/parameters/archived'
- $ref: '#/components/parameters/skipPagination'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
features:
type: array
items:
$ref: '#/components/schemas/FeatureV2'
required:
- features
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v2/features' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postFeatureV2
summary: Create a single feature
description: >-
Creates a new Feature Flag. The caller needs Create access in its
Project, plus Publish access for any environment the Feature Flag starts
enabled in — one that starts disabled everywhere needs Create alone.
Rules are supplied as a top-level `rules` array; each rule includes
`allEnvironments` / `environments` scope fields.
### Naming for human review
The `id` is the Feature Flag's permanent name in the UI and code. Keep
it short (`checkout-express-pay`) and put context in `description`. To
create it disabled, list every environment in `environments` with
`enabled: false`.
### Config-backed features (Config mode)
A JSON feature can be backed by a shared **config** — the config
supplies the base JSON value and schema, and the feature's *rule* values
become override *patches* merged on top (nested objects deep-merge;
arrays and scalars replace). The default value is exactly a config with
no overrides (see below). Config backing is set exclusively through
dedicated fields — never a raw `$extends: ["@config:…"]` inside a value
string (that is rejected). `@const:` references inside values still
work.
- **Top-level (`baseConfig`):** set `valueType: "json"` and `baseConfig:
""` to put the Feature Flag in Config mode. The config must
be live. This is the family root and the base the default value patches.
- **Default value:** unlike rules, the default is exactly a config with
no overrides of its own — send `defaultValue: "{}"` to use `baseConfig`.
To resolve the default to a *descendant* of `baseConfig` instead, set
`defaultValueConfig` to that descendant's key (it must be within
`baseConfig`'s family); omit/null to use `baseConfig` directly.
- **Rules & experiment variations:** each carries its own `config` field
naming the family config that value patches (omit/null to patch the
base). `value` is the override patch.
Example:
```json
{
"id": "checkout-config",
"valueType": "json",
"baseConfig": "purchase-flow",
"defaultValue": "{}",
"rules": [
{ "type": "force", "config": "purchase-flow-vip", "value": "{\"maxItems\": 20}", "allEnvironments": true }
]
}
```
tags:
- features-v2
parameters:
- $ref: '#/components/parameters/skipSchemaValidation'
- $ref: '#/components/parameters/ignoreWarnings'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
pattern: ^[a-zA-Z0-9_.:\|\-]+$
description: >-
Unique, permanent key, shown as the Feature Flag's name in
the UI and used in code. Keep it short. If
`featureRegexValidator` in `GET /api/v1/settings` is set,
follow it (`featureKeyExample` shows the format); otherwise
use kebab-case (e.g. `checkout-express-pay`). Put context in
`description`.
type: string
minLength: 1
archived:
type: boolean
description:
description: >-
Markdown. What the Feature Flag gates and why, rollout plan,
and links. Put context here, not in the key.
type: string
maxLength: 10000
owner:
description: >-
The userId or email address of the owner. If an email
address is provided, it will be used to look up the userId
of the matching organization member. If an ID is provided,
it will be validated as existing in the organization. When
omitted, it defaults to the requesting member: a personal
access token's owner, or the member an organization API key
assumes. An organization API key acting as itself must send
it, or the request fails with a 400.
type: string
project:
description: An associated project ID
type: string
targetingAllProjects:
description: >-
Make this feature discoverable in — and served to — every
project, beyond its primary `project`. Requires the
`targetFeatures` permission (FlagsTarget policy) unscoped to
any project. Governance stays with `project`.
type: boolean
targetingProjects:
description: >-
Secondary project IDs this feature is targeted in and served
to, beyond its primary `project`. Adding a project requires
the `targetFeatures` permission (FlagsTarget policy) in that
project. Governance stays with `project`.
type: array
items:
type: string
valueType:
description: The data type of the feature payload. Boolean by default.
type: string
enum:
- boolean
- string
- number
- json
defaultValue:
description: >-
Default value when feature is enabled. Type must match
`valueType`. In Config mode (`baseConfig` set) the default
must be exactly a config with no overrides: send `"{}"` to
use `baseConfig`, or set `defaultValueConfig` to point at a
descendant.
type: string
baseConfig:
description: >-
Key of the config backing this flag ("Config mode").
Requires `valueType: "json"` and a live config. The config
supplies the base JSON and schema; `defaultValue` and rule
values are override patches on top. null or omitted for a
plain flag.
anyOf:
- type: string
- type: 'null'
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'
tags:
description: >-
Tags for filtering and grouping. Use these instead of
encoding groups in names.
type: array
items:
type: string
rules:
description: >-
Feature rules. Each rule carries its own environment scope
via `allEnvironments` / `environments`.
type: array
items:
anyOf:
- type: object
properties:
description:
description: >-
Short note on why the rule exists (e.g. `Beta
testers only`).
type: string
maxLength: 10000
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted so a GET
response can be posted back unchanged;
`savedGroups` takes precedence if both are sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
pendingRamp:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
description: >-
ISO 8601 date-time, e.g.
"2025-06-01T00:00:00Z".
anyOf:
- type: string
format: date-time
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
id:
type: string
enabled:
type: boolean
type:
type: string
const: force
value:
type: string
config:
description: >-
Key of a config to back this value. When set,
`value` is a JSON override patch merged on top of
the config; omit or null for a plain value.
anyOf:
- type: string
- type: 'null'
sparse:
description: >-
JSON features only. When true, the rule value is a
partial object merged onto the feature's default
value instead of replacing it.
type: boolean
allEnvironments:
description: >-
When true the rule applies to all environments
(default).
type: boolean
environments:
description: >-
Environment IDs the rule applies to. Ignored when
allEnvironments is true; with allEnvironments
false, an omitted or empty list scopes the rule to
no environment.
type: array
items:
type: string
allProjects:
description: >-
When true (the default) the rule applies to every
project the feature is delivered to. Set false and
supply `projects` to scope the rule.
type: boolean
projects:
description: >-
Specific project IDs this rule applies to. Used
when allProjects is false. An empty array scopes
the rule to no project. When the organization
requires registered attributes with project
scoping, the rule's attributes are validated
against these projects rather than the whole
feature's.
type: array
items:
type: string
required:
- type
- value
additionalProperties: false
- type: object
properties:
description:
description: >-
Short note on why the rule exists (e.g. `Beta
testers only`).
type: string
maxLength: 10000
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted so a GET
response can be posted back unchanged;
`savedGroups` takes precedence if both are sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
pendingRamp:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
description: >-
ISO 8601 date-time, e.g.
"2025-06-01T00:00:00Z".
anyOf:
- type: string
format: date-time
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
id:
type: string
enabled:
type: boolean
type:
type: string
const: rollout
value:
type: string
config:
description: >-
Key of a config to back this value. When set,
`value` is a JSON override patch merged on top of
the config; omit or null for a plain value.
anyOf:
- type: string
- type: 'null'
sparse:
description: >-
JSON features only. When true, the rule value is a
partial object merged onto the feature's default
value instead of replacing it.
type: boolean
coverage:
type: number
hashAttribute:
type: string
fallbackAttribute:
description: >-
Used in place of `hashAttribute` when a user lacks
it. Only SDKs with Sticky Bucketing enabled use
it.
type: string
seed:
description: >-
Optional seed for the hash function; defaults to
the rule id
type: string
hashVersion:
anyOf:
- type: number
const: 1
- type: number
const: 2
allEnvironments:
description: >-
When true the rule applies to all environments
(default).
type: boolean
environments:
description: >-
Environment IDs the rule applies to. Ignored when
allEnvironments is true; with allEnvironments
false, an omitted or empty list scopes the rule to
no environment.
type: array
items:
type: string
allProjects:
description: >-
When true (the default) the rule applies to every
project the feature is delivered to. Set false and
supply `projects` to scope the rule.
type: boolean
projects:
description: >-
Specific project IDs this rule applies to. Used
when allProjects is false. An empty array scopes
the rule to no project. When the organization
requires registered attributes with project
scoping, the rule's attributes are validated
against these projects rather than the whole
feature's.
type: array
items:
type: string
required:
- type
- value
- coverage
- hashAttribute
additionalProperties: false
- type: object
properties:
description:
description: >-
Short note on why the rule exists (e.g. `Beta
testers only`).
type: string
maxLength: 10000
id:
type: string
enabled:
type: boolean
type:
type: string
const: experiment-ref
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted so a GET
response can be posted back unchanged;
`savedGroups` takes precedence if both are sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
pendingRamp:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
description: >-
ISO 8601 date-time, e.g.
"2025-06-01T00:00:00Z".
anyOf:
- type: string
format: date-time
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
variations:
type: array
items:
type: object
properties:
value:
type: string
variationId:
type: string
config:
description: >-
Key of a config to back this value. When
set, `value` is a JSON override patch merged
on top of the config; omit or null for a
plain value.
anyOf:
- type: string
- type: 'null'
required:
- value
- variationId
additionalProperties: false
experimentId:
type: string
sparse:
description: >-
JSON features only. When true, the rule value is a
partial object merged onto the feature's default
value instead of replacing it.
type: boolean
allEnvironments:
description: >-
When true the rule applies to all environments
(default).
type: boolean
environments:
description: >-
Environment IDs the rule applies to. Ignored when
allEnvironments is true; with allEnvironments
false, an omitted or empty list scopes the rule to
no environment.
type: array
items:
type: string
allProjects:
description: >-
When true (the default) the rule applies to every
project the feature is delivered to. Set false and
supply `projects` to scope the rule.
type: boolean
projects:
description: >-
Specific project IDs this rule applies to. Used
when allProjects is false. An empty array scopes
the rule to no project. When the organization
requires registered attributes with project
scoping, the rule's attributes are validated
against these projects rather than the whole
feature's.
type: array
items:
type: string
required:
- type
- variations
- experimentId
additionalProperties: false
- type: object
properties:
description:
description: >-
Short note on why the rule exists (e.g. `Beta
testers only`).
type: string
maxLength: 10000
id:
type: string
enabled:
type: boolean
type:
type: string
const: safe-rollout
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted so a GET
response can be posted back unchanged;
`savedGroups` takes precedence if both are sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
pendingRamp:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
description: >-
ISO 8601 date-time, e.g.
"2025-06-01T00:00:00Z".
anyOf:
- type: string
format: date-time
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
controlValue:
type: string
variationValue:
type: string
hashAttribute:
type: string
trackingKey:
type: string
seed:
type: string
safeRolloutId:
description: >-
ID of an existing SafeRollout on this feature.
Bulk POST/PUT cannot create new safe-rollouts; use
POST /v2/features/:id/revisions/:version/rules to
create one.
type: string
status:
type: string
enum:
- running
- released
- rolled-back
- stopped
allEnvironments:
description: >-
When true the rule applies to all environments
(default).
type: boolean
environments:
description: >-
Environment IDs the rule applies to. Ignored when
allEnvironments is true; with allEnvironments
false, an omitted or empty list scopes the rule to
no environment.
type: array
items:
type: string
allProjects:
description: >-
When true (the default) the rule applies to every
project the feature is delivered to. Set false and
supply `projects` to scope the rule.
type: boolean
projects:
description: >-
Specific project IDs this rule applies to. Used
when allProjects is false. An empty array scopes
the rule to no project. When the organization
requires registered attributes with project
scoping, the rule's attributes are validated
against these projects rather than the whole
feature's.
type: array
items:
type: string
required:
- type
- controlValue
- variationValue
- hashAttribute
- safeRolloutId
additionalProperties: false
environments:
description: >-
Per-environment enabled state, keyed by environment ID. An
environment you leave out uses its "Default state for new
features" setting, which may be enabled. To create the
Feature Flag disabled, list every environment with `enabled:
false`. Rules go on the top-level `rules` field.
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
enabled:
description: >-
Whether the Feature Flag is enabled in this
environment.
type: boolean
additionalProperties: false
prerequisites:
description: Feature IDs. Each feature must evaluate to `true`
type: array
items:
type: string
jsonSchema:
description: >-
Use JSON schema to validate the payload of a JSON-type
feature value (enterprise only).
type: string
customFields:
type: object
propertyNames:
type: string
additionalProperties:
type: string
comment:
description: >-
Comment to record on the feature's initial revision.
Defaults to an empty comment.
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
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. 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
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. 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
allowUnscopedRules:
description: >-
When the organization requires rules to target specific
environments or Projects, set to true to save a rule that
applies to All Environments and All Projects. 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:
- id
- valueType
- defaultValue
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
feature:
$ref: '#/components/schemas/FeatureV2'
required:
- feature
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
'422':
description: Error
content:
application/json:
schema:
type: object
description: >-
A rule applies to All Environments and All Projects, which the
organization doesn't allow without `allowUnscopedRules`
properties:
message:
type: string
code:
type: string
enum:
- unscoped_rule
details:
$ref: '#/components/schemas/ApiErrorUnscopedRuleDetails'
required:
- message
- code
- details
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v2/features' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}:
get:
operationId: getFeatureV2
summary: Get a single feature
tags:
- features-v2
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/withRevisions'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
feature:
$ref: '#/components/schemas/FeatureWithRevisionsV2'
required:
- feature
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v2/features/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: updateFeatureV2
summary: Partially update a feature
description: >-
Updates the Feature Flag and immediately publishes a new revision. The
caller needs Edit access in the Feature Flag's Project and Publish
access for every affected environment. When approval is required, use
the revision endpoints instead, unless the caller can bypass draft
approvals.
Other top-level fields are patch-merged: omit a field to leave it
unchanged. The `rules` field, when supplied, replaces the entire `rules`
array in one operation. To preserve existing rules, fetch the Feature
Flag, update the returned `rules` array, and send the complete array
back. Safe-rollout rules round-trip through `safeRolloutId`; use `POST
/v2/features/:id/revisions/:version/rules` to create new ones.
tags:
- features-v2
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/skipSchemaValidation'
- $ref: '#/components/parameters/ignoreWarnings'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
description:
description: >-
Markdown. What the Feature Flag gates and why, rollout plan,
and links. Put context here, not in the key.
type: string
maxLength: 10000
archived:
type: boolean
project:
description: An associated project ID
type: string
targetingAllProjects:
description: >-
Make this feature discoverable in — and served to — every
project, beyond its primary `project`. Requires the
`targetFeatures` permission (FlagsTarget policy) unscoped to
any project. Governance stays with `project`.
type: boolean
targetingProjects:
description: >-
Secondary project IDs this feature is targeted in and served
to, beyond its primary `project`. Adding a project requires
the `targetFeatures` permission (FlagsTarget policy) in that
project. Governance stays with `project`.
type: array
items:
type: string
owner:
description: >-
The userId or email address of the owner. If an email
address is provided, it will be used to look up the userId
of the matching organization member. If an ID is provided,
it will be validated as existing in the organization.
type: string
defaultValue:
type: string
baseConfig:
description: >-
The config backing this flag, fixed at creation. Cannot be
changed by an update — resend the current value or omit it;
a different value is rejected.
anyOf:
- type: string
- type: 'null'
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'
tags:
description: >-
Tags for filtering and grouping. Use these instead of
encoding groups in names. Replaces the existing tags
completely.
type: array
items:
type: string
rules:
description: >-
Replaces all feature rules atomically. Behavior differs from
v1: v1 PUT applies per-environment patches, v2 PUT swaps the
entire `rules` array in one revision. To preserve existing
rules during a partial edit, GET the feature first, mutate
the returned `rules` array, and PUT the full array back.
Safe-rollout rules round-trip via their `safeRolloutId`
(creation requires `POST
/v2/features/:id/revisions/:version/rules`).
type: array
items:
anyOf:
- type: object
properties:
description:
description: >-
Short note on why the rule exists (e.g. `Beta
testers only`).
type: string
maxLength: 10000
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted so a GET
response can be posted back unchanged;
`savedGroups` takes precedence if both are sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
pendingRamp:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
description: >-
ISO 8601 date-time, e.g.
"2025-06-01T00:00:00Z".
anyOf:
- type: string
format: date-time
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
id:
type: string
enabled:
type: boolean
type:
type: string
const: force
value:
type: string
config:
description: >-
Key of a config to back this value. When set,
`value` is a JSON override patch merged on top of
the config; omit or null for a plain value.
anyOf:
- type: string
- type: 'null'
sparse:
description: >-
JSON features only. When true, the rule value is a
partial object merged onto the feature's default
value instead of replacing it.
type: boolean
allEnvironments:
description: >-
When true the rule applies to all environments
(default).
type: boolean
environments:
description: >-
Environment IDs the rule applies to. Ignored when
allEnvironments is true; with allEnvironments
false, an omitted or empty list scopes the rule to
no environment.
type: array
items:
type: string
allProjects:
description: >-
When true (the default) the rule applies to every
project the feature is delivered to. Set false and
supply `projects` to scope the rule.
type: boolean
projects:
description: >-
Specific project IDs this rule applies to. Used
when allProjects is false. An empty array scopes
the rule to no project. When the organization
requires registered attributes with project
scoping, the rule's attributes are validated
against these projects rather than the whole
feature's.
type: array
items:
type: string
required:
- type
- value
additionalProperties: false
- type: object
properties:
description:
description: >-
Short note on why the rule exists (e.g. `Beta
testers only`).
type: string
maxLength: 10000
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted so a GET
response can be posted back unchanged;
`savedGroups` takes precedence if both are sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
pendingRamp:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
description: >-
ISO 8601 date-time, e.g.
"2025-06-01T00:00:00Z".
anyOf:
- type: string
format: date-time
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
id:
type: string
enabled:
type: boolean
type:
type: string
const: rollout
value:
type: string
config:
description: >-
Key of a config to back this value. When set,
`value` is a JSON override patch merged on top of
the config; omit or null for a plain value.
anyOf:
- type: string
- type: 'null'
sparse:
description: >-
JSON features only. When true, the rule value is a
partial object merged onto the feature's default
value instead of replacing it.
type: boolean
coverage:
type: number
hashAttribute:
type: string
fallbackAttribute:
description: >-
Used in place of `hashAttribute` when a user lacks
it. Only SDKs with Sticky Bucketing enabled use
it.
type: string
seed:
description: >-
Optional seed for the hash function; defaults to
the rule id
type: string
hashVersion:
anyOf:
- type: number
const: 1
- type: number
const: 2
allEnvironments:
description: >-
When true the rule applies to all environments
(default).
type: boolean
environments:
description: >-
Environment IDs the rule applies to. Ignored when
allEnvironments is true; with allEnvironments
false, an omitted or empty list scopes the rule to
no environment.
type: array
items:
type: string
allProjects:
description: >-
When true (the default) the rule applies to every
project the feature is delivered to. Set false and
supply `projects` to scope the rule.
type: boolean
projects:
description: >-
Specific project IDs this rule applies to. Used
when allProjects is false. An empty array scopes
the rule to no project. When the organization
requires registered attributes with project
scoping, the rule's attributes are validated
against these projects rather than the whole
feature's.
type: array
items:
type: string
required:
- type
- value
- coverage
- hashAttribute
additionalProperties: false
- type: object
properties:
description:
description: >-
Short note on why the rule exists (e.g. `Beta
testers only`).
type: string
maxLength: 10000
id:
type: string
enabled:
type: boolean
type:
type: string
const: experiment-ref
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted so a GET
response can be posted back unchanged;
`savedGroups` takes precedence if both are sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
pendingRamp:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
description: >-
ISO 8601 date-time, e.g.
"2025-06-01T00:00:00Z".
anyOf:
- type: string
format: date-time
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
variations:
type: array
items:
type: object
properties:
value:
type: string
variationId:
type: string
config:
description: >-
Key of a config to back this value. When
set, `value` is a JSON override patch merged
on top of the config; omit or null for a
plain value.
anyOf:
- type: string
- type: 'null'
required:
- value
- variationId
additionalProperties: false
experimentId:
type: string
sparse:
description: >-
JSON features only. When true, the rule value is a
partial object merged onto the feature's default
value instead of replacing it.
type: boolean
allEnvironments:
description: >-
When true the rule applies to all environments
(default).
type: boolean
environments:
description: >-
Environment IDs the rule applies to. Ignored when
allEnvironments is true; with allEnvironments
false, an omitted or empty list scopes the rule to
no environment.
type: array
items:
type: string
allProjects:
description: >-
When true (the default) the rule applies to every
project the feature is delivered to. Set false and
supply `projects` to scope the rule.
type: boolean
projects:
description: >-
Specific project IDs this rule applies to. Used
when allProjects is false. An empty array scopes
the rule to no project. When the organization
requires registered attributes with project
scoping, the rule's attributes are validated
against these projects rather than the whole
feature's.
type: array
items:
type: string
required:
- type
- variations
- experimentId
additionalProperties: false
- type: object
properties:
description:
description: >-
Short note on why the rule exists (e.g. `Beta
testers only`).
type: string
maxLength: 10000
id:
type: string
enabled:
type: boolean
type:
type: string
const: safe-rollout
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted so a GET
response can be posted back unchanged;
`savedGroups` takes precedence if both are sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
pendingRamp:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
rampScheduleId:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
scheduleType:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
description: >-
ISO 8601 date-time, e.g.
"2025-06-01T00:00:00Z".
anyOf:
- type: string
format: date-time
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
controlValue:
type: string
variationValue:
type: string
hashAttribute:
type: string
trackingKey:
type: string
seed:
type: string
safeRolloutId:
description: >-
ID of an existing SafeRollout on this feature.
Bulk POST/PUT cannot create new safe-rollouts; use
POST /v2/features/:id/revisions/:version/rules to
create one.
type: string
status:
type: string
enum:
- running
- released
- rolled-back
- stopped
allEnvironments:
description: >-
When true the rule applies to all environments
(default).
type: boolean
environments:
description: >-
Environment IDs the rule applies to. Ignored when
allEnvironments is true; with allEnvironments
false, an omitted or empty list scopes the rule to
no environment.
type: array
items:
type: string
allProjects:
description: >-
When true (the default) the rule applies to every
project the feature is delivered to. Set false and
supply `projects` to scope the rule.
type: boolean
projects:
description: >-
Specific project IDs this rule applies to. Used
when allProjects is false. An empty array scopes
the rule to no project. When the organization
requires registered attributes with project
scoping, the rule's attributes are validated
against these projects rather than the whole
feature's.
type: array
items:
type: string
required:
- type
- controlValue
- variationValue
- hashAttribute
- safeRolloutId
additionalProperties: false
environments:
description: >-
Per-environment enabled state. V2 rules are specified on the
top-level `rules` field.
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
enabled:
description: >-
Whether the Feature Flag is enabled in this
environment.
type: boolean
additionalProperties: false
prerequisites:
description: Feature IDs. Each feature must evaluate to `true`
type: array
items:
type: string
jsonSchema:
description: >-
Use JSON schema to validate the payload of a JSON-type
feature value (enterprise only).
type: string
customFields:
type: object
propertyNames:
type: string
additionalProperties:
type: string
holdout:
description: >
Holdout to assign this feature to. Pass `null` to remove the
feature from its current holdout. Omit the field entirely to
leave the holdout unchanged.
anyOf:
- type: object
properties:
id:
description: Holdout ID
type: string
value:
description: >-
The feature value assigned to users in the holdout
treatment group
type: string
required:
- id
- value
additionalProperties: false
- type: 'null'
comment:
description: >-
Comment to record on the revision this update publishes,
when it publishes one. Defaults to "Created via REST API".
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
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. 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
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. 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
allowUnscopedRules:
description: >-
When the organization requires rules to target specific
environments or Projects, set to true to save a rule that
applies to All Environments and All Projects. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
feature:
$ref: '#/components/schemas/FeatureV2'
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:
- feature
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
'422':
description: Error
content:
application/json:
schema:
type: object
description: >-
A rule applies to All Environments and All Projects, which the
organization doesn't allow without `allowUnscopedRules`
properties:
message:
type: string
code:
type: string
enum:
- unscoped_rule
details:
$ref: '#/components/schemas/ApiErrorUnscopedRuleDetails'
required:
- message
- code
- details
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v2/features/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteFeatureV2
summary: Deletes a single feature
description: >-
Permanently deletes a Feature Flag and all of its revisions. The caller
needs Archive & delete access. Deleting a live Feature Flag also
requires Publish access for every environment where it is enabled and
the organization setting "REST API always bypasses approval
requirements". Otherwise, archive the Feature Flag before deleting it.
tags:
- features-v2
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
description: The ID of the deleted feature
example: feature-123
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X DELETE 'https://api.growthbook.io/api/v2/features/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/toggle:
post:
operationId: toggleFeatureV2
summary: Toggle a feature in one or more environments
description: >-
Enables or disables a Feature Flag in one or more environments and
immediately publishes the change. The caller needs Publish access for
every environment in the request. When approval is required, use a draft
revision instead, unless the caller can bypass draft approvals.
tags:
- features-v2
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
reason:
type: string
comment:
description: >-
Comment to record on the revision this toggle publishes,
when it changes any environment. Defaults to "Created via
REST API". (`reason` is recorded in the audit log only.)
type: string
environments:
type: object
propertyNames:
type: string
additionalProperties:
anyOf:
- type: boolean
const: true
- type: boolean
const: false
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '1'
- type: string
const: '0'
- type: number
const: 1
- type: number
const: 0
- type: string
const: ''
required:
- environments
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
feature:
$ref: '#/components/schemas/FeatureV2'
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:
- feature
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST 'https://api.growthbook.io/api/v2/features/{id}/toggle'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revert:
post:
operationId: revertFeatureV2
summary: Revert a feature to a specific revision
description: >-
Restores a previously published revision and immediately publishes the
result as a new revision. The caller needs Revert access for every
affected environment. When approval is required, the request is allowed
only if the caller holds the `FlagsBypassApprovals` policy, or the
organization enables either "REST API always bypasses approval
requirements" or "Allow reverts without approval".
If the restored values no longer match the Feature Flag's current value
type or JSON schema, or restoring an archived state would archive a flag
that live flags or experiments still depend on, the API returns 422 with
`warnings`. Send `"ignoreWarnings": true` to acknowledge those warnings
and continue.
tags:
- features-v2
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
revision:
type: number
comment:
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
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. 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
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. 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:
- revision
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
feature:
$ref: '#/components/schemas/FeatureV2'
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:
- feature
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST 'https://api.growthbook.io/api/v2/features/{id}/revert'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/feature-keys:
get:
operationId: getFeatureKeysV2
summary: Get list of feature keys
tags:
- features-v2
parameters:
- $ref: '#/components/parameters/projectId'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
type: string
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v2/feature-keys' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/stale-features:
get:
operationId: getFeatureStaleV2
summary: Get stale status for one or more features
tags:
- features-v2
parameters:
- $ref: '#/components/parameters/ids'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
features:
description: >-
Map of feature ID to stale status. Only requested features
that were found and readable are included.
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
featureId:
type: string
isStale:
type: boolean
staleReason:
anyOf:
- type: string
enum:
- never-stale
- recently-updated
- active-draft
- has-dependents
- no-rules
- rules-one-sided
- abandoned-draft
- toggled-off
- active-experiment
- temp-rollout
- old-temp-rollout
- has-rules
- type: 'null'
neverStale:
type: boolean
staleByEnv:
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
isStale:
type: boolean
reason:
anyOf:
- type: string
enum:
- no-rules
- rules-one-sided
- abandoned-draft
- toggled-off
- active-experiment
- temp-rollout
- old-temp-rollout
- has-rules
- recently-updated
- active-draft
- has-dependents
- type: 'null'
evaluatesTo:
type: string
tempRollout:
type: string
enum:
- temp-rollout
- old-temp-rollout
required:
- isStale
- reason
additionalProperties: false
required:
- featureId
- isStale
- staleReason
- neverStale
additionalProperties: false
required:
- features
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v2/stale-features' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/feature-revisions:
get:
operationId: listRevisionsV2
summary: List revisions across all features
description: >-
Returns a paginated list of feature revisions across all features in the
organization. Use the `featureId` query parameter to filter to a single
feature. Revision `rules` is a flat array with per-rule scope.
tags:
- feature-revisions-v2
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/skipPagination'
- $ref: '#/components/parameters/featureId'
- $ref: '#/components/parameters/status'
- $ref: '#/components/parameters/author'
- name: mine
in: query
description: >-
If true, return only revisions authored by or contributed to by the
calling user.
schema:
description: >-
If true, return only revisions authored by or contributed to by
the calling user.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
- name: archived
in: query
description: >-
Whether to include revisions for archived features. Defaults to
`false` (non-archived features only). Pass `true` to include
revisions for archived features alongside non-archived ones.
schema:
description: >-
Whether to include revisions for archived features. Defaults to
`false` (non-archived features only). Pass `true` to include
revisions for archived features alongside non-archived ones.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revisions:
type: array
items:
$ref: '#/components/schemas/FeatureRevisionV2'
limit:
type: integer
offset:
type: integer
count:
type: integer
total:
type: integer
hasMore:
type: boolean
nextOffset:
anyOf:
- type: integer
- type: 'null'
required:
- revisions
- limit
- offset
- count
- total
- hasMore
- nextOffset
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v2/feature-revisions' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions:
get:
operationId: getFeatureRevisionsV2
summary: List revisions for a feature
description: >-
Returns a paginated list of revisions for this feature, sorted
newest-first. Revision `rules` is a flat array with per-rule scope.
tags:
- feature-revisions-v2
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/skipPagination'
- $ref: '#/components/parameters/status'
- $ref: '#/components/parameters/author'
- $ref: '#/components/parameters/mine'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revisions:
type: array
items:
$ref: '#/components/schemas/FeatureRevisionV2'
limit:
type: integer
offset:
type: integer
count:
type: integer
total:
type: integer
hasMore:
type: boolean
nextOffset:
anyOf:
- type: integer
- type: 'null'
required:
- revisions
- limit
- offset
- count
- total
- hasMore
- nextOffset
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v2/features/{id}/revisions' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postFeatureRevisionV2
summary: Create a draft revision
description: Creates a new draft revision branched from the current live revision.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/overrideDraftLimit'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
comment:
description: Markdown. What changed and why, for reviewers.
type: string
title:
description: Short draft title (e.g. `Enable for beta testers`).
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
additionalProperties: false
responses:
'200':
description: Resource created
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 POST
'https://api.growthbook.io/api/v2/features/{id}/revisions' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/latest:
get:
operationId: getFeatureRevisionLatestV2
summary: Get the most recent active draft revision
description: >-
Returns the most recently updated active draft revision for the feature.
Returns 404 if no matching draft exists. Filter by status, author, or
use `mine=true` to scope to the calling user's own drafts.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- name: mine
in: query
description: >-
If true, return only the most recent active draft authored by or
contributed to by the calling user.
schema:
description: >-
If true, return only the most recent active draft authored by or
contributed to by the calling user.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
- $ref: '#/components/parameters/status'
- name: author
in: query
description: Filter to drafts created by this user (userId).
schema:
description: Filter to drafts created by this user (userId).
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v2/features/{id}/revisions/latest' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}:
get:
operationId: getFeatureRevisionV2
summary: Get a single feature revision
description: >-
Returns the revision at the specified version for this feature. Revision
`rules` is a flat array with per-rule environment scope.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/diff:
get:
operationId: getFeatureRevisionDiffV2
summary: Diff a revision against another revision
description: >-
Returns a schema-keyed JSON diff between this revision and a baseline.
The same shapes the in-app review surface produces under `Copy as →
Minimal JSON` / `Full JSON`: `minimal` lists only what changed (with
id-keyed arrays bucketed into added/removed/modified items and reorder
detection), while `full` returns the complete before/after content of
the revision. Lifecycle fields (version, status, comment, date,
createdBy, publishedBy) are excluded from the diff body and echoed via
`from` / `to` instead. Defaults to diffing against the revision's own
`baseVersion`; pass `?base=live` to diff against the current live
revision, or `?base=` for an arbitrary historical one.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
- $ref: '#/components/parameters/format'
- $ref: '#/components/parameters/base'
responses:
'200':
description: Successful response
content:
application/json:
schema:
anyOf:
- type: object
properties:
diff:
type: object
properties:
name:
description: The feature key.
type: string
type:
type: string
const: feature
from:
description: >-
Version number this revision was diffed against
(the before).
type: integer
to:
description: Version number being diffed (the after).
type: integer
changes:
type: array
items:
type: object
properties:
field:
type: string
change:
type: string
enum:
- added
- removed
- modified
required:
- field
- change
additionalProperties: {}
supplemental:
type: array
items:
type: object
properties:
name:
type: string
type:
type: string
change:
type: string
enum:
- added
- removed
- modified
required:
- name
- type
- change
additionalProperties: {}
required:
- name
- type
- from
- to
- changes
additionalProperties: false
required:
- diff
additionalProperties: false
- type: object
properties:
diff:
type: object
properties:
name:
description: The feature key.
type: string
type:
type: string
const: feature
from:
description: >-
Version number this revision was diffed against
(the before).
type: integer
to:
description: Version number being diffed (the after).
type: integer
before:
type: object
propertyNames:
type: string
additionalProperties: {}
after:
type: object
propertyNames:
type: string
additionalProperties: {}
supplemental:
type: array
items:
type: object
properties:
name:
type: string
type:
type: string
before:
anyOf:
- {}
- type: 'null'
after:
anyOf:
- {}
- type: 'null'
required:
- name
- type
- before
- after
additionalProperties: false
required:
- name
- type
- from
- to
- before
- after
additionalProperties: false
required:
- diff
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/diff'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/metadata:
put:
operationId: putFeatureRevisionMetadataV2
summary: Update revision metadata
tags:
- feature-revisions-v2
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:
comment:
description: Markdown. What changed and why, for reviewers.
type: string
title:
description: Short draft title (e.g. `Enable for beta testers`).
type: string
description:
description: >-
Markdown. What the Feature Flag gates and why, rollout plan,
and links. Put context here, not in the key.
type: string
owner:
description: >-
The userId or email address of the owner. If an email
address is provided, it will be used to look up the userId
of the matching organization member. If an ID is provided,
it will be validated as existing in the organization.
type: string
project:
type: string
targetingAllProjects:
description: >-
Stage delivering this feature to every project. Requires the
`targetFeatures` permission unscoped to any project.
type: boolean
targetingProjects:
description: >-
Stage the secondary project IDs this feature is delivered
to. Adding a project requires the `targetFeatures`
permission (FlagsTarget policy) in that project.
type: array
items:
type: string
tags:
type: array
items:
type: string
neverStale:
type: boolean
customFields:
type: object
propertyNames:
type: string
additionalProperties: {}
jsonSchema:
description: >-
Validation schema to stage on the draft. The server sets
`date`, so don't send it.
type: object
properties:
schemaType:
type: string
enum:
- schema
- simple
schema:
type: string
simple:
type: object
properties:
type:
type: string
enum:
- object
- object[]
- primitive
- primitive[]
fields:
type: array
items:
type: object
properties:
key:
type: string
maxLength: 64
type:
type: string
enum:
- integer
- float
- string
- boolean
required:
type: boolean
default:
type: string
maxLength: 256
description:
type: string
maxLength: 10000
enum:
maxItems: 256
type: array
items:
type: string
maxLength: 256
min:
type: number
max:
type: number
nullable:
type: boolean
jsonSchema:
type: string
required:
- key
- type
- required
- default
- description
- enum
additionalProperties: false
additionalProperties:
type: boolean
invariants:
type: array
items:
type: object
properties:
name:
type: string
maxLength: 128
rule:
type: string
message:
type: string
maxLength: 10000
required:
- name
- rule
- message
additionalProperties: false
required:
- type
- fields
additionalProperties: false
enabled:
type: boolean
required:
- schemaType
- schema
- simple
- enabled
additionalProperties: false
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
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}/metadata'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/default-value:
put:
operationId: putFeatureRevisionDefaultValueV2
summary: Set the default value in a draft revision
tags:
- feature-revisions-v2
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
- $ref: '#/components/parameters/skipSchemaValidation'
- $ref: '#/components/parameters/ignoreWarnings'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
defaultValue:
description: >-
New default value. In Config mode (feature has
`baseConfig`), the default must be exactly a config with no
overrides: send `"{}"` to use `baseConfig`, or set
`defaultValueConfig` to point at a descendant.
type: string
defaultValueConfig:
description: >-
Key of a config within the feature's `baseConfig` family
that the default value resolves to (the base itself or a
descendant). The default is exactly that config with no
overrides; pass `null` to use `baseConfig`. Do not embed
`@config:` in `defaultValue` — use this field.
anyOf:
- type: string
- type: 'null'
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
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. 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
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. 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:
- defaultValue
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}/default-value'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/prerequisites:
put:
operationId: putFeatureRevisionPrerequisitesV2
summary: Set feature-level prerequisites in a draft revision
description: >-
Sets the feature-level prerequisites for this revision. Each
prerequisite must be a boolean feature flag; the gate is always
'prerequisite flag is on'. The condition is applied automatically — only
the flag ID is required.
tags:
- feature-revisions-v2
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:
prerequisites:
description: >-
List of prerequisite boolean flags. When any prerequisite
flag is off for a user, this flag returns its defaultValue
for that user.
type: array
items:
type: object
properties:
id:
description: ID of a boolean feature flag
type: string
required:
- id
additionalProperties: false
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:
- prerequisites
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}/prerequisites'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/holdout:
put:
operationId: putFeatureRevisionHoldoutV2
summary: Set holdout in a draft revision
tags:
- feature-revisions-v2
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:
holdout:
anyOf:
- type: object
properties:
id:
type: string
value:
type: string
required:
- id
- value
additionalProperties: false
- type: 'null'
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:
- holdout
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}/holdout'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/archive:
put:
operationId: putFeatureRevisionArchiveV2
summary: Set archived state in a draft revision
tags:
- feature-revisions-v2
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'
/v2/features/{id}/revisions/{version}/toggle:
post:
operationId: postFeatureRevisionToggleV2
summary: Toggle an environment on/off in a draft revision
tags:
- feature-revisions-v2
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:
environment:
type: string
enabled:
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:
- environment
- enabled
additionalProperties: false
responses:
'200':
description: Resource created
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 POST
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/toggle'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/rules:
post:
operationId: postFeatureRevisionRuleAddV2
summary: Add a rule to a draft revision
description: >-
Appends a new rule to the revision's rule list. Supply `allEnvironments:
true` on the rule to target all environments, or `environments: [...]`
to scope to specific ones.
**Scheduling:** For `force` and `rollout` rules, attach a schedule via
`rampSchedule` (multi-step ramp) or `schedule` (simple start/end window)
— these create standalone ramp actions and set `pendingRamp: "create"`
on the rule. For `experiment-ref` and `safe-rollout` rules, only
`schedule` is supported and is stored as legacy schedule fields on the
rule itself (`rampSchedule` is not available for these rule types).
tags:
- feature-revisions-v2
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
- $ref: '#/components/parameters/skipSchemaValidation'
- $ref: '#/components/parameters/ignoreWarnings'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
rule:
anyOf:
- title: Targeting Rule
$ref: '#/components/schemas/Targeting Rule'
- title: Experiment Rule
$ref: '#/components/schemas/Experiment Rule'
- title: Safe Rollout Rule
$ref: '#/components/schemas/Safe Rollout Rule'
rampSchedule:
description: >-
Multi-step ramp schedule for force/rollout rules. Not
supported for experiment-ref or safe-rollout rules. Mutually
exclusive with `schedule`.
type: object
properties:
name:
type: string
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:
- type: string
format: date-time
- type: 'null'
cutoffDate:
description: >-
ISO 8601 date-time, e.g. "2025-07-01T00:00:00Z". The
ramp ends at this time.
anyOf:
- type: string
format: date-time
- type: 'null'
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. Mutually exclusive with
the deprecated `exposureQueryId`.
type: object
properties:
id:
description: >-
The ID of one of the data source's assignment
queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the
query must declare. Required when selecting a
different assignment query that declares
several. Otherwise defaults to the current
identifier type, or the query's only one. Null
is treated as omitted, so a response's value can
be sent back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
exposureQueryId:
deprecated: true
description: >-
Deprecated: use `exposureQuery`. Rejected when
selecting a different assignment query that declares
several identifier types; set
`exposureQuery.identifierType` instead.
type: string
required:
- datasourceId
- guardrailMetricIds
additionalProperties: false
lockdownConfig:
type: object
properties:
mode:
type: string
enum:
- none
- locked
required:
- mode
additionalProperties: false
requiresStartApproval:
anyOf:
- type: boolean
- type: 'null'
additionalProperties: false
schedule:
description: >-
Simple start/end date window. For force/rollout rules this
creates a standalone ramp action; for
experiment-ref/safe-rollout rules this sets legacy schedule
fields on the rule. Mutually exclusive with `rampSchedule`.
type: object
properties:
startDate:
description: >-
ISO 8601 date-time, e.g. "2025-06-01T00:00:00Z". Rule is
enabled at this time.
anyOf:
- type: string
format: date-time
- type: 'null'
endDate:
description: >-
ISO 8601 date-time, e.g. "2025-07-01T00:00:00Z". Rule is
disabled at this time.
anyOf:
- type: string
format: date-time
- type: 'null'
additionalProperties: false
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
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. 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
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. 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
allowUnscopedRules:
description: >-
When the organization requires rules to target specific
environments or Projects, set to true to save a rule that
applies to All Environments and All Projects. 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:
- rule
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
'422':
description: Error
content:
application/json:
schema:
type: object
description: >-
A rule applies to All Environments and All Projects, which the
organization doesn't allow without `allowUnscopedRules`
properties:
message:
type: string
code:
type: string
enum:
- unscoped_rule
details:
$ref: '#/components/schemas/ApiErrorUnscopedRuleDetails'
required:
- message
- code
- details
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/rules'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/rules/{ruleId}:
put:
operationId: putFeatureRevisionRuleV2
summary: Update a rule in a draft revision
description: >-
Patches fields on an existing rule (identified by `ruleId`). The rule
`type` cannot be changed. Scope can be updated via `allEnvironments` /
`environments` patch fields.
**Scheduling:** For `force` and `rollout` rules, update the schedule via
`rampSchedule` (multi-step ramp) or `schedule` (simple start/end window)
— these manage standalone ramp actions and set `pendingRamp: "create"`
on the rule. For `experiment-ref` and `safe-rollout` rules, only
`schedule` is supported and updates legacy schedule fields on the rule
itself (`rampSchedule` is not available for these rule types).
tags:
- feature-revisions-v2
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
- $ref: '#/components/parameters/ruleId'
- $ref: '#/components/parameters/skipSchemaValidation'
- $ref: '#/components/parameters/ignoreWarnings'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
rule:
type: object
properties:
description:
description: >-
Short note on why the rule exists (e.g. `Beta testers
only`).
type: string
enabled:
type: boolean
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
type:
type: string
enum:
- force
- rollout
- experiment-ref
- safe-rollout
value:
type: string
config:
description: >-
Force/rollout rules only. Key of a config to back the
value (or null to detach). When set, `value` is a JSON
override patch merged on top of the config. Omit to
leave the existing config backing unchanged.
anyOf:
- type: string
- type: 'null'
sparse:
type: boolean
coverage:
type: number
minimum: 0
maximum: 1
hashAttribute:
type: string
fallbackAttribute:
type: string
seed:
type: string
hashVersion:
anyOf:
- type: number
const: 1
- type: number
const: 2
experimentId:
type: string
variations:
type: array
items:
type: object
properties:
variationId:
type: string
value:
type: string
config:
description: >-
Key of a config to back this variation value (or
null to detach). When set, `value` is a JSON
override patch merged on top of the config.
anyOf:
- type: string
- type: 'null'
required:
- variationId
- value
additionalProperties: false
controlValue:
type: string
variationValue:
type: string
allEnvironments:
description: Omit both scope fields to keep the current scope.
type: boolean
environments:
description: >-
Environment IDs the rule applies to. Ignored when
allEnvironments is true.
type: array
items:
type: string
additionalProperties: false
rampSchedule:
description: >-
Multi-step ramp schedule for force/rollout rules. Not
supported for experiment-ref or safe-rollout rules. Mutually
exclusive with `schedule`.
type: object
properties:
name:
type: string
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:
- type: string
format: date-time
- type: 'null'
cutoffDate:
description: >-
ISO 8601 date-time, e.g. "2025-07-01T00:00:00Z". The
ramp ends at this time.
anyOf:
- type: string
format: date-time
- type: 'null'
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. Mutually exclusive with
the deprecated `exposureQueryId`.
type: object
properties:
id:
description: >-
The ID of one of the data source's assignment
queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the
query must declare. Required when selecting a
different assignment query that declares
several. Otherwise defaults to the current
identifier type, or the query's only one. Null
is treated as omitted, so a response's value can
be sent back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
exposureQueryId:
deprecated: true
description: >-
Deprecated: use `exposureQuery`. Rejected when
selecting a different assignment query that declares
several identifier types; set
`exposureQuery.identifierType` instead.
type: string
required:
- datasourceId
- guardrailMetricIds
additionalProperties: false
lockdownConfig:
type: object
properties:
mode:
type: string
enum:
- none
- locked
required:
- mode
additionalProperties: false
requiresStartApproval:
anyOf:
- type: boolean
- type: 'null'
additionalProperties: false
schedule:
description: >-
Simple start/end date window. For force/rollout rules this
manages a standalone ramp action; for
experiment-ref/safe-rollout rules this updates legacy
schedule fields on the rule. Mutually exclusive with
`rampSchedule`.
type: object
properties:
startDate:
description: >-
ISO 8601 date-time, e.g. "2025-06-01T00:00:00Z". Rule is
enabled at this time.
anyOf:
- type: string
format: date-time
- type: 'null'
endDate:
description: >-
ISO 8601 date-time, e.g. "2025-07-01T00:00:00Z". Rule is
disabled at this time.
anyOf:
- type: string
format: date-time
- type: 'null'
additionalProperties: false
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
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. 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
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. 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
allowUnscopedRules:
description: >-
When the organization requires rules to target specific
environments or Projects, set to true to save a rule that
applies to All Environments and All Projects. 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:
- rule
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'
'422':
description: Error
content:
application/json:
schema:
type: object
description: >-
A rule applies to All Environments and All Projects, which the
organization doesn't allow without `allowUnscopedRules`
properties:
message:
type: string
code:
type: string
enum:
- unscoped_rule
details:
$ref: '#/components/schemas/ApiErrorUnscopedRuleDetails'
required:
- message
- code
- details
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/rules/{ruleId}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteFeatureRevisionRuleV2
summary: Delete a rule from a draft revision
description: >-
Removes the rule from the revision. Any pending ramp actions for this
rule are also cleared.
tags:
- feature-revisions-v2
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
- $ref: '#/components/parameters/ruleId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
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
additionalProperties: false
responses:
'200':
description: Resource deleted
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 DELETE
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/rules/{ruleId}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/rules/reorder:
post:
operationId: postFeatureRevisionRulesReorderV2
summary: Reorder rules in the revision
description: >-
Replaces the flat global rule order. `ruleIds` must contain **exactly**
the set of all existing rule IDs in the revision — no additions,
omissions, or duplicates.
tags:
- feature-revisions-v2
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:
ruleIds:
type: array
items:
type: string
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:
- ruleIds
additionalProperties: false
responses:
'200':
description: Resource created
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 POST
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/rules/reorder'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/rules/{ruleId}/ramp-schedule:
put:
operationId: putFeatureRevisionRuleRampScheduleV2
summary: Set ramp schedule for a rule
description: >-
Queues a revision-controlled ramp action for this rule. If the rule
already has a live ramp schedule, this stores an `update` action applied
on publish; otherwise it stores a `create` action. No live schedule
config changes are applied immediately by this endpoint.
You can build the ramp from a template (`templateId`) and set the
rollback anchor (`startState`) in the same request — e.g. pull in a
template and pass `startState: { "coverage": 0 }` so a rollback returns
the rule to 0%.
tags:
- feature-revisions-v2
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
- $ref: '#/components/parameters/ruleId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
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:
- type: string
format: date-time
- type: 'null'
cutoffDate:
description: >-
ISO 8601 date-time, e.g. "2025-07-01T00:00:00Z". The ramp
ends at this time.
anyOf:
- type: string
format: date-time
- type: 'null'
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. Mutually exclusive with the
deprecated `exposureQueryId`.
type: object
properties:
id:
description: >-
The ID of one of the data source's assignment
queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the query
must declare. Required when selecting a different
assignment query that declares several. Otherwise
defaults to the current identifier type, or the
query's only one. Null is treated as omitted, so a
response's value can be sent back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
exposureQueryId:
deprecated: true
description: >-
Deprecated: use `exposureQuery`. Rejected when selecting
a different assignment query that declares several
identifier types; set `exposureQuery.identifierType`
instead.
type: string
required:
- datasourceId
- guardrailMetricIds
additionalProperties: false
lockdownConfig:
type: object
properties:
mode:
type: string
enum:
- none
- locked
required:
- mode
additionalProperties: false
requiresStartApproval:
anyOf:
- type: boolean
- type: 'null'
environment:
deprecated: true
type: string
startState:
description: >-
The rule state to roll back to (the rollback/jump-to-start
anchor). Merged onto the rule's current state, so `{
"coverage": 0 }` keeps existing targeting but rolls back to
0%. Steps accumulate on it, and it is the only place a plan
sets `hashAttribute` (plus optional `seed` and
`hashVersion`), which a partial-coverage step on a force
rule requires unless the rule has one. On create, omitting
it infers the anchor from the rule's current coverage (and
returns a warning if that isn't 0%); on update of a live
schedule, omitting it leaves the existing anchor unchanged.
type: object
properties:
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
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
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
warnings:
description: >-
Non-fatal advisories about how the request was
interpreted.
type: array
items:
type: string
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}/rules/{ruleId}/ramp-schedule'
\
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteFeatureRevisionRuleRampScheduleV2
summary: Remove ramp schedule from a rule
description: >-
Clears any pending ramp action for this rule. If a live ramp schedule
exists, queues a detach that removes it on publish — the rule will show
`pendingRamp: "detach"`. If only a pending create exists, it is removed
and `pendingRamp` is cleared.
tags:
- feature-revisions-v2
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
- $ref: '#/components/parameters/ruleId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
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
additionalProperties: false
responses:
'200':
description: Resource deleted
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 DELETE
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/rules/{ruleId}/ramp-schedule'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/request-review:
post:
operationId: postFeatureRevisionRequestReviewV2
summary: Request review for a draft revision
description: >-
Moves the draft into the `pending-review` state and notifies reviewers.
Set `autoPublishOnApproval` to `true` to publish the revision
automatically the moment it is approved (GitHub auto-merge model). This
requires the org to have auto-publish-on-approval enabled for the
feature and the caller to have publish permission; the auto-publish then
executes with the caller's authority.
Set `scheduledPublishAt` to a future ISO date-time to defer the
auto-publish until that date (it still also requires approval when
review is required). Use `scheduledPublishLockEdits` to freeze edits to
this draft while the schedule is pending, and
`scheduledPublishLockOthers` to block publishing other drafts of this
feature in the meantime.
Neither can be set on a draft whose rules would take a draft experiment
live, since an automatic publish doesn't start the experiment. Schedule
the experiment's start instead; starting it publishes the draft.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
comment:
description: >-
Markdown. What changed and why, for reviewers. Replaces the
draft's comment; leaving it out clears it.
type: string
autoPublishOnApproval:
type: boolean
scheduledPublishAt:
anyOf:
- type: string
format: date-time
- type: 'null'
scheduledPublishLockEdits:
type: boolean
scheduledPublishLockOthers:
type: boolean
additionalProperties: false
responses:
'200':
description: Resource created
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 POST
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/request-review'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/schedule-publish:
post:
operationId: postFeatureRevisionSchedulePublishV2
summary: Schedule (or cancel) a deferred publish for a draft revision
description: >-
Schedules the draft to publish on or after `scheduledPublishAt`. When
approval is required, publishing waits until the draft is also approved.
Send `scheduledPublishAt: null` to cancel the schedule.
Set `lockEdits` to prevent content changes while the schedule is
pending; rebasing remains allowed. Set `lockOthers` to prevent other
drafts of this Feature Flag from being published until this schedule
runs or is canceled. The caller needs Publish access, and that access is
checked again when the schedule runs. A caller with Bypass draft
approvals access can schedule an unapproved draft by sending
`bypassApproval: true`. That schedule must be canceled and recreated
before it can be changed, and a later edit that would reset an approval
also drops the bypass.
A draft whose rules would take a draft experiment live can't be
scheduled, since a scheduled publish doesn't start the experiment.
Schedule the experiment's start instead; starting it publishes the
draft.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
scheduledPublishAt:
description: >-
When to publish, as an RFC3339 timestamp (e.g.
`2026-01-31T09:00:00Z` or `2026-01-31T02:00:00-07:00`), or
`null` to cancel a pending schedule.
anyOf:
- type: string
format: date-time
- type: 'null'
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
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. 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
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. 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
lockEdits:
type: boolean
lockOthers:
type: boolean
bypassApproval:
type: boolean
required:
- scheduledPublishAt
additionalProperties: false
responses:
'200':
description: Resource created
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 POST
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/schedule-publish'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/submit-review:
post:
operationId: postFeatureRevisionSubmitReviewV2
summary: Submit a review on a draft revision
description: >-
Submits an `approve`, `request-changes`, or `comment` review on the
draft. The verdict belongs to whoever the request acts as; see [Naming
who asked](/api/introduction#naming-who-asked). No one can rule on a
draft they created. Contributors cannot approve their own drafts when
`blockSelfApproval` is enabled.
When `action` is `approve` and the revision has `autoPublishOnApproval`
enabled, the revision is automatically published after approval. The
response includes `autoPublished: true` when this happens. Pass
`skipAutoPublish: true` to approve without triggering auto-publish.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
comment:
description: Markdown. Why you approved, requested changes or commented.
type: string
action:
description: >-
`approve`, `request-changes` or `comment`. Defaults to
`comment`, which doesn't change whether the draft is
approved.
type: string
enum:
- approve
- request-changes
- comment
skipAutoPublish:
type: boolean
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
autoPublished:
type: boolean
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/submit-review'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/recall-review:
post:
operationId: postFeatureRevisionRecallReviewV2
summary: Recall a review request (revert to draft)
description: >-
Retracts the review request, returning the revision from
`pending-review`, `changes-requested`, or `approved` back to `draft`.
Allowed for any user with draft-management permission on the feature
(the same permission required to request review), not only the original
requester. Existing review log entries are preserved as audit history
but any in-flight reviewer verdicts (Approved / Requested Changes)
submitted during this review cycle no longer count — submitting a fresh
`request-review` starts a new cycle.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/recall-review'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/undo-review:
post:
operationId: postFeatureRevisionUndoReviewV2
summary: Undo a reviewer's own review verdict
description: >-
Reviewer retracts their own verdict. The verdict belongs to whoever the
request acts as; see [Naming who
asked](/api/introduction#naming-who-asked). No one can rule on a draft
they created. The revision status rewinds to the state implied by the
remaining active verdicts from other reviewers: any outstanding
`Requested Changes` → `changes-requested`, else any outstanding
`Approved` → `approved`, else `pending-review`. Existing review comments
are preserved. If the retraction resolves the revision to `approved` and
auto-publish-on-approval is armed, the revision is published.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/undo-review'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/log:
get:
operationId: getFeatureRevisionLogV2
summary: List the activity log for a revision
description: >-
Returns every log entry for the revision — content edits (rules, default
value, rebases), review lifecycle events (review requested, approved,
changes requested, recalled, undone), comments, and other audit events —
sorted oldest-first.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
log:
type: array
items:
$ref: '#/components/schemas/log'
required:
- log
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/log'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/log/{logId}:
put:
operationId: putFeatureRevisionLogCommentV2
summary: Edit the comment text of an owned log entry
description: >-
Author of a `Comment`, `Approved`, or `Requested Changes` log entry can
rewrite its comment text. The entry's action and other audit-trail
metadata remain immutable; this only mutates `value.comment`. Other
audit events (e.g. `Review Requested`, system events) are not editable.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
- $ref: '#/components/parameters/logId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
comment:
description: New comment text. Replaces existing comment text.
type: string
required:
- comment
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
status:
type: number
const: 200
required:
- status
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}/log/{logId}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteFeatureRevisionLogEntryV2
summary: Delete an owned revision Comment entry
description: >-
Author of a `Comment` log entry can delete it. Verdict entries
(Approved, Requested Changes, Review Requested) and other audit-trail
events are immutable. To retract a verdict use `/undo-review`; to
retract a review request use `/recall-review`.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
- $ref: '#/components/parameters/logId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
status:
type: number
const: 200
required:
- status
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/log/{logId}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/merge-status:
get:
operationId: getFeatureRevisionMergeStatusV2
summary: Get merge status for a draft revision
description: >-
Runs the three-way merge between the draft and the current live version
without applying it. Conflicts are granular: each conflicting field gets
its own key, and rules conflict individually (`rules.`, plus
`rules.order` for competing reorders). Pass the returned `liveVersion`
as `expectedLiveVersion` when rebasing. Also reports `rebaseRequired` so
callers can detect ahead of time whether the publish endpoint will block
until the draft is rebased.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
liveVersion:
description: >-
The current live version the merge was computed against.
Echo this back as `expectedLiveVersion` when rebasing.
type: number
draftDateUpdated:
format: date-time
description: >-
The draft's last-modified timestamp at merge time. Echo
this back as `expectedDraftDateUpdated` when rebasing to
guard against concurrent draft edits.
type: string
conflicts:
type: array
items:
$ref: '#/components/schemas/conflicts'
result:
type: object
properties:
defaultValue:
type: string
rules:
type: array
items: {}
environmentsEnabled:
type: object
propertyNames:
type: string
additionalProperties:
type: boolean
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
archived:
type: boolean
metadata:
type: object
properties:
releaseType:
type: string
riskLevel:
type: string
additionalProperties: {}
holdout:
anyOf:
- type: object
properties:
id:
type: string
value:
type: string
required:
- id
- value
additionalProperties: false
- type: 'null'
additionalProperties: false
rebaseRequired:
description: >-
Whether the draft must be rebased before it can be
published. This is true when the merge has conflicts, or
when the organization requires rebasing and the draft or
its approval is out of date. If there are no conflicts, a
caller with Bypass draft approvals access can send
`ignoreWarnings: true` to force-publish instead.
type: boolean
required:
- success
- liveVersion
- draftDateUpdated
- conflicts
- rebaseRequired
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/merge-status'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/rebase/preview:
post:
operationId: postFeatureRevisionRebasePreviewV2
summary: Preview a rebase without applying it
description: >-
Dry-run of the rebase: runs the same three-way merge with the supplied
`conflictResolutions` and returns every conflict (resolved and
unresolved) plus the merged result once all are resolved — without
modifying the draft. Use it to iterate on resolutions before committing
them via the rebase endpoint.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
conflictResolutions:
description: >-
Map of conflict key → resolution. Keys come from the
returned conflicts: `defaultValue`, `prerequisites`,
`archived`, `holdout`, `environmentsEnabled.`,
`metadata.`, `rules.`, and `rules.order`.
`overwrite` keeps the draft's version of that item;
`discard` keeps live's. The blanket `rules` key applies one
strategy to all rule-level conflicts.
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- overwrite
- discard
expectedLiveVersion:
description: >-
Optimistic-concurrency guard: the live version the
resolutions were authored against (as returned by
merge-status or rebase preview). If live has since moved,
the request fails with `409` instead of applying resolutions
to different conflicts.
type: integer
expectedDraftDateUpdated:
description: >-
Optimistic-concurrency guard for the draft side: the draft's
`draftDateUpdated` timestamp as returned by merge-status or
rebase preview. If the draft has been modified since (e.g.
by a co-author), the request fails with `409` instead of
applying resolutions against changed draft content.
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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
liveVersion:
description: >-
The current live version the merge was computed against.
Echo this back as `expectedLiveVersion` when rebasing.
type: number
draftDateUpdated:
format: date-time
description: >-
The draft's last-modified timestamp at merge time. Echo
this back as `expectedDraftDateUpdated` when rebasing to
guard against concurrent draft edits.
type: string
conflicts:
type: array
items:
$ref: '#/components/schemas/conflicts'
result:
type: object
properties:
defaultValue:
type: string
rules:
type: array
items: {}
environmentsEnabled:
type: object
propertyNames:
type: string
additionalProperties:
type: boolean
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
archived:
type: boolean
metadata:
type: object
properties:
releaseType:
type: string
riskLevel:
type: string
additionalProperties: {}
holdout:
anyOf:
- type: object
properties:
id:
type: string
value:
type: string
required:
- id
- value
additionalProperties: false
- type: 'null'
additionalProperties: false
required:
- success
- liveVersion
- draftDateUpdated
- conflicts
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/rebase/preview'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/rebase:
post:
operationId: postFeatureRevisionRebaseV2
summary: Rebase a draft revision onto the current live version
description: >-
Updates the draft's base revision to match the currently-live revision,
applying the draft's changes on top. Supply `conflictResolutions` to
resolve conflicting items individually — including per-rule
(`rules.`) and rule-order (`rules.order`) conflicts. Supply
`expectedLiveVersion` and/or `expectedDraftDateUpdated` (both returned
by merge-status and rebase preview) to fail fast with `409` if either
side changes between conflict review and submission. Unresolved
conflicts also respond with `409`.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
conflictResolutions:
description: >-
Map of conflict key → resolution. Keys come from the
returned conflicts: `defaultValue`, `prerequisites`,
`archived`, `holdout`, `environmentsEnabled.`,
`metadata.`, `rules.`, and `rules.order`.
`overwrite` keeps the draft's version of that item;
`discard` keeps live's. The blanket `rules` key applies one
strategy to all rule-level conflicts.
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- overwrite
- discard
expectedLiveVersion:
description: >-
Optimistic-concurrency guard: the live version the
resolutions were authored against (as returned by
merge-status or rebase preview). If live has since moved,
the request fails with `409` instead of applying resolutions
to different conflicts.
type: integer
expectedDraftDateUpdated:
description: >-
Optimistic-concurrency guard for the draft side: the draft's
`draftDateUpdated` timestamp as returned by merge-status or
rebase preview. If the draft has been modified since (e.g.
by a co-author), the request fails with `409` instead of
applying resolutions against changed draft content.
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
additionalProperties: false
responses:
'200':
description: Resource created
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 POST
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/rebase'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/publish:
post:
operationId: postFeatureRevisionPublishV2
summary: Publish a draft revision
description: >-
Publishes the draft and makes its changes live. The caller needs Publish
access for every affected environment. When approval is required, the
draft must be approved unless the caller has Bypass draft approvals
access. If the organization requires rebasing, an out-of-date draft must
be rebased first; an authorized caller can instead send `ignoreWarnings:
true` to force-publish it. Any pending ramp actions in `pendingRamp` are
applied as part of the same operation. A 422 response lists every
blocking gate and the available resolution.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
- $ref: '#/components/parameters/skipSchemaValidation'
- $ref: '#/components/parameters/ignoreWarnings'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
comment:
description: >-
Note recorded in the audit log for this publish. Also
becomes the draft's comment if the draft has none; otherwise
the existing draft comment is kept.
type: string
bypassApproval:
description: >-
Deprecated and ignored. Approval is bypassed automatically
when the caller has Bypass draft approvals access for this
resource or when the organization enables the REST API
approval bypass. Otherwise, the revision must be approved
before it can be published.
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. 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
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. 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
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. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
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:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/publish'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/discard:
post:
operationId: postFeatureRevisionDiscardV2
summary: Discard a draft revision
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/discard'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/reopen:
post:
operationId: postFeatureRevisionReopenV2
summary: Reopen a discarded revision as a draft
description: >-
Returns a `discarded` revision to `draft` status so it can be edited,
reviewed, and published. Prior review state is not restored — the draft
must go back through review if approvals are required.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/reopen'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/features/{id}/revisions/{version}/revert:
post:
operationId: postFeatureRevisionRevertV2
summary: Revert the feature to a prior revision
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
strategy:
type: string
enum:
- draft
- publish
comment:
description: Markdown. What changed and why, for reviewers.
type: string
title:
description: Short draft title (e.g. `Enable for beta testers`).
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
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. 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
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. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
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:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/revert'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/archetypes:
get:
operationId: listArchetypes
summary: Get the organization's archetypes
tags:
- archetypes
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
archetypes:
type: array
items:
$ref: '#/components/schemas/Archetype'
required:
- archetypes
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/archetypes' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postArchetype
summary: Create a single archetype
tags:
- archetypes
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name (e.g. `Logged-out US visitor`).
type: string
description:
description: Put context here, not in the name.
type: string
maxLength: 10000
isPublic:
description: >-
Whether to make this Archetype available to other team
members
type: boolean
attributes:
description: The attributes to set when using this Archetype
type: object
propertyNames:
type: string
additionalProperties: {}
projects:
type: array
items:
type: string
environments:
description: >-
Limit this Archetype to specific environments. Omit or leave
empty to apply to all environments.
type: array
items:
type: string
required:
- name
- isPublic
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
archetype:
$ref: '#/components/schemas/Archetype'
required:
- archetype
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/archetypes' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/archetypes/{id}:
get:
operationId: getArchetype
summary: Get a single archetype
tags:
- archetypes
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
archetype:
$ref: '#/components/schemas/Archetype'
required:
- archetype
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/archetypes/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: putArchetype
summary: Update a single archetype
tags:
- archetypes
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name (e.g. `Logged-out US visitor`).
type: string
description:
description: Put context here, not in the name.
type: string
maxLength: 10000
isPublic:
description: >-
Whether to make this Archetype available to other team
members
type: boolean
attributes:
description: The attributes to set when using this Archetype
type: object
propertyNames:
type: string
additionalProperties: {}
projects:
type: array
items:
type: string
environments:
description: >-
Limit this Archetype to specific environments. Omit or leave
empty to apply to all environments.
type: array
items:
type: string
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
archetype:
$ref: '#/components/schemas/Archetype'
required:
- archetype
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X PUT 'https://api.growthbook.io/api/v1/archetypes/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"description":"New description"}'
delete:
operationId: deleteArchetype
summary: Deletes a single archetype
tags:
- archetypes
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE 'https://api.growthbook.io/api/v1/archetypes/abc123'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/experiments:
get:
operationId: listExperiments
summary: Get all experiments
tags:
- experiments
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/projectId'
- $ref: '#/components/parameters/datasourceId'
- $ref: '#/components/parameters/trackingKey'
- $ref: '#/components/parameters/experimentId'
- name: status
in: query
description: ''
schema:
type: string
enum:
- draft
- running
- stopped
- $ref: '#/components/parameters/q'
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/result'
- $ref: '#/components/parameters/tag'
- $ref: '#/components/parameters/implementationType'
- $ref: '#/components/parameters/metricId'
- $ref: '#/components/parameters/bandits'
- name: archived
in: query
description: >-
Filter by archived status. Set to `true` to return only archived
experiments, `false` to exclude them. If omitted, both archived and
non-archived experiments are returned.
schema:
description: >-
Filter by archived status. Set to `true` to return only archived
experiments, `false` to exclude them. If omitted, both archived
and non-archived experiments are returned.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
- $ref: '#/components/parameters/sortBy'
- $ref: '#/components/parameters/sortOrder'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
experiments:
type: array
items:
$ref: '#/components/schemas/Experiment'
required:
- experiments
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/experiments' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postExperiment
summary: Create a single experiment
description: >-
Creates a new experiment.
### Naming for human review
Keep `name` short; put reasoning in `hypothesis` and context in
`description`. `trackingKey` is sent with exposure events, so keep it
short and stable.
tags:
- experiments
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
datasourceId:
description: >-
ID for the [DataSource](#tag/DataSource_model). Can only be
set if a templateId is not provided.
type: string
assignmentQuery:
description: >-
The assignment query, grouping its ID with the identifier
type analyzed on. Mutually exclusive with the deprecated
`assignmentQueryId`. Can only be set if a templateId is not
provided.
type: object
properties:
id:
description: The ID of one of the data source's assignment queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the query must
declare. Required when selecting a different assignment
query that declares several. Otherwise defaults to the
current identifier type, or the query's only one. Null
is treated as omitted, so a response's value can be sent
back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
assignmentQueryId:
deprecated: true
description: >-
Deprecated: use `assignmentQuery`. Rejected when selecting a
different assignment query that declares several identifier
types; set `assignmentQuery.identifierType` instead. Can
only be set if a templateId is not provided.
type: string
trackingKey:
description: >-
Key sent with exposure events. Keep it short, in kebab-case
(usually the Feature Flag key). If your organization
requires a tracking key format, a key that doesn't match is
rejected with `invalid_tracking_key`. Changing it after
launch splits exposures across two keys.
type: string
bypassDuplicateKeyCheck:
description: >-
If true, allow creating an experiment even if another
experiment with the same tracking key already exists. This
is ignored if the organization requires unique tracking keys
as a rule. 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
name:
description: >-
Short display name (e.g. `Express checkout button`). Put
reasoning in `hypothesis` and context in `description`.
type: string
type:
type: string
enum:
- standard
- multi-armed-bandit
project:
description: Project ID which the experiment belongs to
type: string
templateId:
description: >-
ID of the
[ExperimentTemplate](#tag/ExperimentTemplate_model) this
experiment was created from. Template fields are applied by
default and overridden by explicitly provided payload
fields.
type: string
hypothesis:
description: Markdown. If we change X, metric Y will move because Z.
type: string
description:
description: Markdown. Put context here, not in the name.
type: string
maxLength: 10000
tags:
description: >-
Tags for filtering and grouping. Use these instead of
encoding groups in names.
type: array
items:
type: string
metrics:
type: array
items:
type: string
secondaryMetrics:
type: array
items:
type: string
guardrailMetrics:
type: array
items:
type: string
activationMetric:
description: Users must convert on this metric before being included
type: string
segmentId:
description: Only users in this segment will be included
type: string
queryFilter:
description: WHERE clause to add to the default experiment query
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. When
omitted, it defaults to the requesting member: a personal
access token's owner, or the member an organization API key
assumes. An organization API key acting as itself leaves it
empty.
type: string
archived:
type: boolean
status:
type: string
enum:
- draft
- running
- stopped
autoRefresh:
type: boolean
hashAttribute:
type: string
fallbackAttribute:
type: string
attributeScopeAllProjects:
description: >-
Picker preference: show attributes from all projects in this
experiment's targeting UI instead of only those in scope for
its project and linked features. Does not loosen enforcement
— when the organization requires registered attributes with
project scoping, out-of-scope attributes are still rejected.
type: boolean
hashVersion:
anyOf:
- type: number
const: 1
- type: number
const: 2
disableStickyBucketing:
description: >-
When true, disables Sticky Bucketing for this experiment. If
omitted, defaults to your organization's Sticky Bucketing
setting for new experiments. Sticky Bucketing only takes
effect when it is also enabled at the organization level.
type: boolean
bucketVersion:
type: integer
minimum: 0
minBucketVersion:
type: integer
minimum: 0
releasedVariationId:
type: string
excludeFromPayload:
type: boolean
inProgressConversions:
type: string
enum:
- loose
- strict
attributionModel:
description: >-
Setting attribution model to `"experimentDuration"` is the
same as selecting "Ignore Conversion Windows" for the
Conversion Window Override. Setting it to
`"lookbackOverride"` requires a `lookbackOverride` object to
be provided.
type: string
enum:
- firstExposure
- experimentDuration
- lookbackOverride
lookbackOverride:
description: >-
Controls the lookback override for the experiment. For type
"window", value must be a non-negative number and valueUnit
is required.
type: object
properties:
type:
type: string
enum:
- date
- window
value:
description: >-
For "window" type - non-negative numeric value (e.g. 7
for 7 days). For "date" type a date string.
anyOf:
- description: >-
For "window" type - non-negative numeric value (e.g.
7 for 7 days). For "date" type a date string.
type: number
- format: date-time
description: >-
For "window" type - non-negative numeric value (e.g.
7 for 7 days). For "date" type a date string.
type: string
valueUnit:
description: Used when type is "window". Defaults to "days".
type: string
enum:
- minutes
- hours
- days
- weeks
required:
- type
- value
additionalProperties: false
statsEngine:
type: string
enum:
- bayesian
- frequentist
variations:
minItems: 2
type: array
items:
type: object
properties:
id:
description: >-
Stable variation id. On update, an omitted id is
filled from the stored variation with the same key, or
the same position, when the number of variations is
unchanged.
type: string
variationId:
description: >-
Alias for `id`. Mirrors the GET response. `id` takes
precedence.
type: string
key:
description: >-
Key sent with exposure events (e.g. `0`, `1`).
Changing it after launch splits exposures.
type: string
name:
description: Short label shown in results (e.g. `Control`).
type: string
description:
description: What this variation changes.
type: string
maxLength: 10000
screenshots:
type: array
items:
type: object
properties:
path:
type: string
width:
type: number
height:
type: number
description:
type: string
maxLength: 10000
required:
- path
additionalProperties: false
required:
- key
- name
additionalProperties: false
phases:
type: array
items:
type: object
properties:
name:
description: Short phase label (e.g. `Main`).
type: string
dateStarted:
format: date-time
type: string
dateEnded:
format: date-time
type: string
reasonForStopping:
type: string
seed:
type: string
coverage:
type: number
minimum: 0
maximum: 1
namespace:
type: object
properties:
namespaceId:
type: string
enabled:
type: boolean
range:
minItems: 2
maxItems: 2
type: array
items:
type: number
ranges:
type: array
items:
type: array
prefixItems:
- type: number
- type: number
required:
- namespaceId
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
reason:
description: >-
Deprecated: use `reasonForStopping`. Takes precedence
if set.
deprecated: true
type: string
condition:
description: >-
Deprecated: use `targetingCondition`. Takes precedence
if set.
deprecated: true
type: string
targetingCondition:
description: >-
Targeting condition as a JSON string. Mirrors the GET
response.
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted so a GET
response can be posted back unchanged; `savedGroups`
takes precedence if both are sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
variationWeights:
description: >-
Deprecated: use `trafficSplit`. Takes precedence if
set.
deprecated: true
type: array
items:
type: number
minimum: 0
maximum: 1
trafficSplit:
description: Per-variation weights. Mirrors the GET response.
type: array
items:
type: object
properties:
variationId:
type: string
weight:
type: number
minimum: 0
maximum: 1
required:
- variationId
- weight
additionalProperties: false
required:
- name
- dateStarted
additionalProperties: false
regressionAdjustmentEnabled:
description: >-
Controls whether regression adjustment (CUPED) is enabled
for experiment analyses
type: boolean
sequentialTestingEnabled:
description: Only applicable to frequentist analyses
type: boolean
sequentialTestingTuningParameter:
type: number
shareLevel:
type: string
enum:
- public
- organization
banditScheduleValue:
type: number
banditScheduleUnit:
type: string
enum:
- days
- hours
banditBurnInValue:
type: number
banditBurnInUnit:
type: string
enum:
- days
- hours
banditConversionWindowValue:
type: number
banditConversionWindowUnit:
type: string
enum:
- days
- hours
postStratificationEnabled:
description: When null, the organization default is used.
anyOf:
- description: When null, the organization default is used.
type: boolean
- description: When null, the organization default is used.
type: 'null'
decisionFrameworkSettings:
description: >-
Controls the decision framework and metric overrides for the
experiment. Replaces the entire stored object on update
(does not patch individual fields).
type: object
properties:
decisionCriteriaId:
type: string
decisionFrameworkMetricOverrides:
type: array
items:
type: object
properties:
id:
description: ID of the metric to override settings for.
type: string
targetMDE:
description: >-
The target relative MDE to use for the metric,
expressed as proportions (e.g. use 0.1 for 10%).
Must be greater than 0.
type: number
exclusiveMinimum: 0
required:
- id
additionalProperties: false
additionalProperties: false
metricOverrides:
description: >-
Per-metric analysis overrides for this experiment. Replaces
the entire stored array (does not patch individual entries).
type: array
items:
description: >-
Per-metric analysis overrides stored on the experiment
(matches internal metricOverrides).
type: object
properties:
id:
description: ID of the metric to override settings for.
type: string
windowType:
type: string
enum:
- conversion
- lookback
- ''
windowHours:
type: number
delayHours:
type: number
properPriorOverride:
description: >-
Must be true for the override to take effect. If true,
the other proper prior settings in this object will be
used if present.
type: boolean
properPriorEnabled:
type: boolean
properPriorMean:
type: number
properPriorStdDev:
type: number
exclusiveMinimum: 0
regressionAdjustmentOverride:
description: >-
Must be true for the override to take effect. If true,
the other regression adjustment settings in this
object will be used if present.
type: boolean
regressionAdjustmentEnabled:
type: boolean
regressionAdjustmentDays:
type: number
required:
- id
additionalProperties: false
defaultDashboardId:
description: ID of the default dashboard for this experiment.
type: string
customFields:
type: object
propertyNames:
type: string
additionalProperties:
type: string
customMetricSlices:
description: >-
Custom slices that apply to ALL applicable metrics in the
experiment
type: array
items:
type: object
properties:
slices:
type: array
items:
type: object
properties:
column:
type: string
levels:
type: array
items:
type: string
required:
- column
- levels
additionalProperties: false
required:
- slices
additionalProperties: false
precomputedUnitDimensionIds:
maxItems: 3
type: array
items:
type: string
statusUpdateSchedule:
type: object
properties:
startAt:
description: >-
ISO datetime when the experiment should start. Must be
in the future. Setting or clearing this field
invalidates any existing staged start
(`nextScheduledStatusUpdate`); call POST
/experiments/{id}/start to stage the new schedule.
format: date-time
type: string
stopAt:
description: >-
ISO datetime when the experiment should stop. Resolved
from `stopAfter` at start when a relative end was set.
format: date-time
type: string
stopAfter:
description: >-
Relative end offset. Deferred: resolved to a concrete
`stopAt` at the experiment's actual start (or off
`dateStarted` when already running).
type: object
properties:
value:
type: integer
exclusiveMinimum: 0
unit:
type: string
enum:
- hours
- days
required:
- value
- unit
additionalProperties: false
scheduledStopPlan:
description: >-
End-of-experiment automation applied at the scheduled
end. Required whenever a `stopAt` or `stopAfter` is set
(any mode, including `notify`).
$ref: '#/components/schemas/ScheduledStopPlan'
additionalProperties: false
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:
- trackingKey
- name
- variations
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
experiment:
$ref: '#/components/schemas/Experiment'
required:
- experiment
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/experiments' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/experiments/results:
get:
operationId: listExperimentResults
summary: Get latest results for many experiments
description: >-
Returns the latest non-dimension snapshot for each experiment matching
the filters. Use this to scan results across a portfolio in one call.
Pagination semantics:
- `total` is the count of experiments matching the filters.
- `count` is the length of the returned `experimentResults` array.
- Experiments without a completed snapshot are omitted from
`experimentResults`, so `count` may be less than the page slice and a
page may legitimately return `count: 0` while `hasMore: true`.
- `hasMore` and `nextOffset` advance over experiments matching the
filters, not over returned results.
Use the per-experiment `GET /experiments/{id}/results` endpoint to
inspect specific phases or dimensions.
tags:
- experiments
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/projectId'
- $ref: '#/components/parameters/datasourceId'
- $ref: '#/components/parameters/trackingKey'
- name: status
in: query
description: ''
schema:
type: string
enum:
- draft
- running
- stopped
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
experimentResults:
type: array
items:
$ref: '#/components/schemas/ExperimentResults'
required:
- experimentResults
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/experiments/results' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/experiments/{id}:
get:
operationId: getExperiment
summary: Get a single experiment
tags:
- experiments
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
experiment:
$ref: '#/components/schemas/ExperimentWithEnhancedStatus'
required:
- experiment
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/experiments/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: updateExperiment
summary: Update a single experiment
description: >-
Setting `status` from draft to running starts the experiment as `POST
/experiments/{id}/start` does, judged on the experiment as this update
leaves it, with `skipChecklist` in this body. Changing `archived`
archives or unarchives it as `POST /experiments/{id}/archive` and
`/unarchive` do.
tags:
- experiments
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
datasourceId:
description: >-
Changing it needs an `assignmentQueryId` from the new one,
and drops the metrics, segment and unit dimensions that
aren't from it.
type: string
assignmentQuery:
description: >-
The assignment query, grouping its ID with the identifier
type analyzed on. Mutually exclusive with the deprecated
`assignmentQueryId`.
type: object
properties:
id:
description: The ID of one of the data source's assignment queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the query must
declare. Required when selecting a different assignment
query that declares several. Otherwise defaults to the
current identifier type, or the query's only one. Null
is treated as omitted, so a response's value can be sent
back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
assignmentQueryId:
deprecated: true
description: >-
Deprecated: use `assignmentQuery`. Rejected when selecting a
different assignment query that declares several identifier
types; set `assignmentQuery.identifierType` instead.
type: string
trackingKey:
description: >-
Key sent with exposure events. Keep it short, in kebab-case
(usually the Feature Flag key). If your organization
requires a tracking key format, a key that doesn't match is
rejected with `invalid_tracking_key`. Changing it after
launch splits exposures across two keys.
type: string
bypassDuplicateKeyCheck:
description: >-
If true, allow updating the tracking key even if another
experiment with the same tracking key already exist. This is
ignored if the organization requires unique tracking keys as
a rule. 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
name:
description: >-
Short display name (e.g. `Express checkout button`). Put
reasoning in `hypothesis` and context in `description`.
type: string
type:
type: string
enum:
- standard
- multi-armed-bandit
bypassApproval:
description: >-
Deprecated and ignored. Approval is bypassed automatically
when the caller has Bypass draft approvals access for this
resource or when the organization enables the REST API
approval bypass. Otherwise, the revision must be approved
before it can be published.
type: boolean
project:
description: Project ID which the experiment belongs to
type: string
hypothesis:
description: Markdown. If we change X, metric Y will move because Z.
type: string
description:
description: Markdown. Put context here, not in the name.
type: string
maxLength: 10000
tags:
description: >-
Tags for filtering and grouping. Use these instead of
encoding groups in names.
type: array
items:
type: string
metrics:
type: array
items:
type: string
secondaryMetrics:
type: array
items:
type: string
guardrailMetrics:
type: array
items:
type: string
activationMetric:
description: Users must convert on this metric before being included
type: string
segmentId:
description: Only users in this segment will be included
type: string
queryFilter:
description: WHERE clause to add to the default experiment query
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
archived:
type: boolean
linkedChanges:
description: >-
Required while the experiment still serves through linked
changes. "materialize" keeps a stopped experiment's released
variation as a permanent force rule on each linked Feature
Flag; "remove" acknowledges that the linked changes stop
serving.
type: string
enum:
- materialize
- remove
status:
type: string
enum:
- draft
- running
- stopped
autoRefresh:
type: boolean
hashAttribute:
type: string
fallbackAttribute:
type: string
attributeScopeAllProjects:
description: >-
Picker preference: show attributes from all projects in this
experiment's targeting UI instead of only those in scope for
its project and linked features. Does not loosen enforcement
— when the organization requires registered attributes with
project scoping, out-of-scope attributes are still rejected.
type: boolean
hashVersion:
anyOf:
- type: number
const: 1
- type: number
const: 2
disableStickyBucketing:
type: boolean
bucketVersion:
type: integer
minimum: 0
minBucketVersion:
type: integer
minimum: 0
results:
description: >-
The result status of the experiment. Maps to
resultSummary.status in the GET response.
type: string
enum:
- dnf
- won
- lost
- inconclusive
winner:
description: >-
The index of the winning variation (0-indexed). Maps to
resultSummary.winner (variation ID) in the GET response.
type: number
analysis:
description: >-
Analysis summary or conclusions for the experiment. Maps to
resultSummary.conclusions in the GET response.
type: string
releasedVariationId:
description: >-
The ID of the released variation. Maps to
resultSummary.releasedVariationId in the GET response.
type: string
excludeFromPayload:
description: >-
If true, the experiment is excluded from the SDK payload.
Maps to resultSummary.excludeFromPayload in the GET
response.
type: boolean
inProgressConversions:
type: string
enum:
- loose
- strict
attributionModel:
description: >-
Setting attribution model to `"experimentDuration"` is the
same as selecting "Ignore Conversion Windows" for the
Conversion Window Override. Setting it to
`"lookbackOverride"` requires a `lookbackOverride` object to
be provided.
type: string
enum:
- firstExposure
- experimentDuration
- lookbackOverride
lookbackOverride:
description: >-
Controls the lookback override for the experiment. For type
"window", value must be a non-negative number and valueUnit
is required.
type: object
properties:
type:
type: string
enum:
- date
- window
value:
description: >-
For "window" type - non-negative numeric value (e.g. 7
for 7 days). For "date" type a date string.
anyOf:
- description: >-
For "window" type - non-negative numeric value (e.g.
7 for 7 days). For "date" type a date string.
type: number
- format: date-time
description: >-
For "window" type - non-negative numeric value (e.g.
7 for 7 days). For "date" type a date string.
type: string
valueUnit:
description: Used when type is "window". Defaults to "days".
type: string
enum:
- minutes
- hours
- days
- weeks
required:
- type
- value
additionalProperties: false
statsEngine:
type: string
enum:
- bayesian
- frequentist
variations:
minItems: 2
type: array
items:
type: object
properties:
id:
description: >-
Stable variation id. On update, an omitted id is
filled from the stored variation with the same key, or
the same position, when the number of variations is
unchanged.
type: string
variationId:
description: >-
Alias for `id`. Mirrors the GET response. `id` takes
precedence.
type: string
key:
description: >-
Key sent with exposure events (e.g. `0`, `1`).
Changing it after launch splits exposures.
type: string
name:
description: Short label shown in results (e.g. `Control`).
type: string
description:
description: What this variation changes.
type: string
maxLength: 10000
screenshots:
type: array
items:
type: object
properties:
path:
type: string
width:
type: number
height:
type: number
description:
type: string
maxLength: 10000
required:
- path
additionalProperties: false
required:
- key
- name
additionalProperties: false
phases:
type: array
items:
type: object
properties:
name:
type: string
dateStarted:
format: date-time
type: string
dateEnded:
format: date-time
type: string
reasonForStopping:
type: string
seed:
type: string
coverage:
type: number
minimum: 0
maximum: 1
namespace:
type: object
properties:
namespaceId:
type: string
enabled:
type: boolean
range:
minItems: 2
maxItems: 2
type: array
items:
type: number
ranges:
type: array
items:
type: array
prefixItems:
- type: number
- type: number
required:
- namespaceId
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
reason:
description: >-
Deprecated: use `reasonForStopping`. Takes precedence
if set.
deprecated: true
type: string
condition:
description: >-
Deprecated: use `targetingCondition`. Takes precedence
if set.
deprecated: true
type: string
targetingCondition:
description: >-
Targeting condition as a JSON string. Mirrors the GET
response.
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
savedGroupTargeting:
description: >-
Deprecated — use `savedGroups`. Accepted so a GET
response can be posted back unchanged; `savedGroups`
takes precedence if both are sent.
deprecated: true
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
variationWeights:
description: >-
Deprecated: use `trafficSplit`. Takes precedence if
set.
deprecated: true
type: array
items:
type: number
minimum: 0
maximum: 1
trafficSplit:
description: Per-variation weights. Mirrors the GET response.
type: array
items:
type: object
properties:
variationId:
type: string
weight:
type: number
minimum: 0
maximum: 1
required:
- variationId
- weight
additionalProperties: false
required:
- name
- dateStarted
additionalProperties: false
regressionAdjustmentEnabled:
description: >-
Controls whether regression adjustment (CUPED) is enabled
for experiment analyses
type: boolean
sequentialTestingEnabled:
description: Only applicable to frequentist analyses
type: boolean
sequentialTestingTuningParameter:
type: number
shareLevel:
type: string
enum:
- public
- organization
banditScheduleValue:
type: number
banditScheduleUnit:
type: string
enum:
- days
- hours
banditBurnInValue:
type: number
banditBurnInUnit:
type: string
enum:
- days
- hours
banditConversionWindowValue:
type: number
banditConversionWindowUnit:
type: string
enum:
- days
- hours
postStratificationEnabled:
description: When null, the organization default is used.
anyOf:
- description: When null, the organization default is used.
type: boolean
- description: When null, the organization default is used.
type: 'null'
decisionFrameworkSettings:
description: >-
Controls the decision framework and metric overrides for the
experiment. Replaces the entire stored object on update
(does not patch individual fields).
type: object
properties:
decisionCriteriaId:
type: string
decisionFrameworkMetricOverrides:
type: array
items:
type: object
properties:
id:
description: ID of the metric to override settings for.
type: string
targetMDE:
description: >-
The target relative MDE to use for the metric,
expressed as proportions (e.g. use 0.1 for 10%).
Must be greater than 0.
type: number
exclusiveMinimum: 0
required:
- id
additionalProperties: false
additionalProperties: false
metricOverrides:
description: >-
Per-metric analysis overrides for this experiment. Replaces
the entire stored array (does not patch individual entries).
type: array
items:
description: >-
Per-metric analysis overrides stored on the experiment
(matches internal metricOverrides).
type: object
properties:
id:
description: ID of the metric to override settings for.
type: string
windowType:
type: string
enum:
- conversion
- lookback
- ''
windowHours:
type: number
delayHours:
type: number
properPriorOverride:
description: >-
Must be true for the override to take effect. If true,
the other proper prior settings in this object will be
used if present.
type: boolean
properPriorEnabled:
type: boolean
properPriorMean:
type: number
properPriorStdDev:
type: number
exclusiveMinimum: 0
regressionAdjustmentOverride:
description: >-
Must be true for the override to take effect. If true,
the other regression adjustment settings in this
object will be used if present.
type: boolean
regressionAdjustmentEnabled:
type: boolean
regressionAdjustmentDays:
type: number
required:
- id
additionalProperties: false
defaultDashboardId:
description: ID of the default dashboard for this experiment.
type: string
customFields:
type: object
propertyNames:
type: string
additionalProperties:
type: string
customMetricSlices:
description: >-
Custom slices that apply to ALL applicable metrics in the
experiment
type: array
items:
type: object
properties:
slices:
type: array
items:
type: object
properties:
column:
type: string
levels:
type: array
items:
type: string
required:
- column
- levels
additionalProperties: false
required:
- slices
additionalProperties: false
statusUpdateSchedule:
anyOf:
- description: >-
Scheduled start/end. Set to `null` to remove. Provide
any of `startAt`, `stopAt`, or `stopAfter` (a deferred
relative end resolved at start). End-of-experiment
automation is set via the nested `scheduledStopPlan`,
which is required whenever a `stopAt` or `stopAfter` is
set.
type: object
properties:
startAt:
description: >-
ISO datetime when the experiment should start. Must
be in the future. Setting or clearing this field
invalidates any existing staged start
(`nextScheduledStatusUpdate`); call POST
/experiments/{id}/start to stage the new schedule.
format: date-time
type: string
stopAt:
description: >-
ISO datetime when the experiment should stop.
Resolved from `stopAfter` at start when a relative
end was set.
format: date-time
type: string
stopAfter:
description: >-
Relative end offset. Deferred: resolved to a
concrete `stopAt` at the experiment's actual start
(or off `dateStarted` when already running).
type: object
properties:
value:
type: integer
exclusiveMinimum: 0
unit:
type: string
enum:
- hours
- days
required:
- value
- unit
additionalProperties: false
scheduledStopPlan:
description: >-
End-of-experiment automation applied at the
scheduled end. Required whenever a `stopAt` or
`stopAfter` is set (any mode, including `notify`).
$ref: '#/components/schemas/ScheduledStopPlan'
additionalProperties: false
- type: 'null'
precomputedUnitDimensionIds:
maxItems: 3
type: array
items:
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
skipChecklist:
description: >-
When `status` starts a draft: start past its incomplete
launch checklist items, as `POST /experiments/{id}/start`
does. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
experiment:
$ref: '#/components/schemas/Experiment'
bypassedGates:
description: >-
Gates this start skipped or bypassed. Present only when
there were some.
type: array
items:
type: object
properties:
key:
description: >-
The checklist item, or `rampLocked:` for
a linked Feature Flag a ramp locks.
type: string
type:
description: >-
Gate kind: "checklist-item", "approval-required",
"merge-conflict", "unrelated-draft-changes",
"permission-denied" or "ramp-locked".
type: string
outcome:
type: string
const: bypassed
via:
description: >-
How it was passed: `skipChecklist`, the caller's
permission (`bypassApprovalPermission`), or the
organization's REST API approval bypass
(`restApiBypassesReviews`).
type: string
enum:
- ignoreWarnings
- skipSchemaValidation
- skipHooks
- bypassApprovalPermission
- restApiBypassesReviews
- revertsBypassApproval
- skipChecklist
required:
- key
- type
- outcome
- via
additionalProperties: false
publishedFeatureDrafts:
description: >-
The linked Feature Flag drafts the start published.
Present only when it published some.
type: array
items:
$ref: '#/components/schemas/publishedFeatureDrafts'
required:
- experiment
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
'409':
description: Conflict
content:
application/json:
schema:
oneOf:
- type: object
description: >-
An experiment start is blocked by its launch checklist or
a linked Feature Flag
properties:
message:
type: string
code:
type: string
enum:
- checklist_incomplete
details:
$ref: >-
#/components/schemas/ApiErrorChecklistIncompleteDetails
required:
- message
- code
- details
- type: object
description: One or more linked feature drafts could not be published
properties:
message:
type: string
code:
type: string
enum:
- pending_draft_publish_failed
details:
$ref: >-
#/components/schemas/ApiErrorPendingDraftPublishFailedDetails
required:
- message
- code
- details
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/experiments/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteExperiment
summary: Delete an experiment
description: >-
Archive first: a live experiment can only be deleted when the
organization allows the REST API to bypass approval requirements. Linked
Feature Flags lose their experiment rule unless `linkedChanges` is
"materialize".
tags:
- experiments
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/linkedChanges'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
description: The ID of the deleted experiment
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X DELETE 'https://api.growthbook.io/api/v1/experiments/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/experiments/{id}/start-checklist:
get:
operationId: getExperimentStartChecklist
summary: Get an experiment pre-launch checklist status
tags:
- experiments
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
checklistItems:
type: array
items:
$ref: '#/components/schemas/checklistItems'
status:
description: '`notReady` while there''s any gate.'
type: string
enum:
- ready
- notReady
gates:
description: >-
Each incomplete required item, and each linked Feature
Flag a ramp locks, as a gate. A refused start returns the
blocking ones in `gates`.
type: array
items:
$ref: '#/components/schemas/gates'
required:
- checklistItems
- status
- gates
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/experiments/exp_abc123/start-checklist'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/experiments/{id}/results:
get:
operationId: getExperimentResults
summary: Get results for an experiment
tags:
- experiments
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/phase'
- $ref: '#/components/parameters/dimension'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
experiment:
$ref: '#/components/schemas/Experiment'
result:
$ref: '#/components/schemas/ExperimentResults'
required:
- experiment
- result
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/experiments/{id}/results' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/experiments/{id}/archive:
post:
operationId: postExperimentArchive
summary: Archive an experiment
description: >-
An archived experiment leaves the SDK payload. Refused while a running
experiment or a temporary rollout still serves through linked changes
unless `linkedChanges` says what happens to them.
tags:
- experiments
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
linkedChanges:
description: >-
Required while the experiment still serves through linked
changes. "materialize" keeps a stopped experiment's released
variation as a permanent force rule on each linked Feature
Flag; "remove" acknowledges that the linked changes stop
serving.
type: string
enum:
- materialize
- remove
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
experiment:
$ref: '#/components/schemas/ExperimentWithEnhancedStatus'
required:
- experiment
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/experiments/{id}/archive' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/experiments/{id}/unarchive:
post:
operationId: postExperimentUnarchive
summary: Unarchive an experiment
tags:
- experiments
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
experiment:
$ref: '#/components/schemas/ExperimentWithEnhancedStatus'
required:
- experiment
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/experiments/{id}/unarchive' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/experiments/{id}/start:
post:
operationId: postExperimentStart
summary: Start/Stage an experiment
description: >-
Starts an experiment or stages it for a future start if a
`statusUpdateSchedule` is set on the experiment. Both check the launch
checklist that `GET /experiments/{id}/start-checklist` returns, as
gates. An incomplete item refuses the start with `checklist_incomplete`
unless `skipChecklist` is set; a linked Feature Flag blocker refuses it
either way. The refusal lists each blocking gate in `gates`, with the
flag or permission that gets past it and a route that resolves it. A
linked Feature Flag draft that still needs approval, or a flag locked by
a ramp, is bypassed automatically when the caller has Bypass draft
approvals access for that flag or the organization enables the REST API
approval bypass. A start reports what it got past in `bypassedGates` and
the drafts it published in `publishedFeatureDrafts`; if a draft can't
publish, for example because it needs a rebase, the start fails with
`pending_draft_publish_failed` before any is published. A staged start
carries the caller's Bypass draft approvals access to when it runs, for
the drafts as they were when it was staged: if one has changed since, or
the caller has lost that access, it needs approval like any other. The
organization's REST API approval bypass doesn't carry to a staged start.
tags:
- experiments
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
skipChecklist:
description: >-
If true, skips validating the experiment satisfies all
pre-launch checklist items. 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
bypassApproval:
description: >-
Deprecated and ignored. Approval is bypassed automatically
when the caller has Bypass draft approvals access for this
resource or when the organization enables the REST API
approval bypass. Otherwise, the revision must be approved
before it can be published.
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. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
experiment:
$ref: '#/components/schemas/ExperimentWithEnhancedStatus'
message:
description: >-
Present only when the request staged a future scheduled
start instead of starting the experiment immediately.
type: string
bypassedGates:
description: >-
Gates this start skipped or bypassed. Present only when
there were some.
type: array
items:
type: object
properties:
key:
description: >-
The checklist item, or `rampLocked:` for
a linked Feature Flag a ramp locks.
type: string
type:
description: >-
Gate kind: "checklist-item", "approval-required",
"merge-conflict", "unrelated-draft-changes",
"permission-denied" or "ramp-locked".
type: string
outcome:
type: string
const: bypassed
via:
description: >-
How it was passed: `skipChecklist`, the caller's
permission (`bypassApprovalPermission`), or the
organization's REST API approval bypass
(`restApiBypassesReviews`).
type: string
enum:
- ignoreWarnings
- skipSchemaValidation
- skipHooks
- bypassApprovalPermission
- restApiBypassesReviews
- revertsBypassApproval
- skipChecklist
required:
- key
- type
- outcome
- via
additionalProperties: false
publishedFeatureDrafts:
description: >-
The linked Feature Flag drafts the start published.
Present only when it published some.
type: array
items:
$ref: '#/components/schemas/publishedFeatureDrafts'
required:
- experiment
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
'409':
description: Conflict
content:
application/json:
schema:
oneOf:
- type: object
description: >-
An experiment start is blocked by its launch checklist or
a linked Feature Flag
properties:
message:
type: string
code:
type: string
enum:
- checklist_incomplete
details:
$ref: >-
#/components/schemas/ApiErrorChecklistIncompleteDetails
required:
- message
- code
- details
- type: object
description: One or more linked feature drafts could not be published
properties:
message:
type: string
code:
type: string
enum:
- pending_draft_publish_failed
details:
$ref: >-
#/components/schemas/ApiErrorPendingDraftPublishFailedDetails
required:
- message
- code
- details
- type: object
description: Resource is not in a valid status for this operation
properties:
message:
type: string
code:
type: string
enum:
- invalid_status
details:
$ref: '#/components/schemas/ApiErrorInvalidStatusDetails'
required:
- message
- code
- details
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/experiments/exp_abc123/start' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/experiments/{id}/start-checklist/manual/complete:
post:
operationId: postExperimentStartChecklistManualComplete
summary: Mark manual pre-launch checklist items complete
tags:
- experiments
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
keys:
description: >-
Manual pre-launch checklist item keys to mark as complete
(auto-computed items cannot be updated via this endpoint).
minItems: 1
type: array
items:
type: string
required:
- keys
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
checklistItems:
type: array
items:
$ref: '#/components/schemas/checklistItems'
status:
description: '`notReady` while there''s any gate.'
type: string
enum:
- ready
- notReady
gates:
description: >-
Each incomplete required item, and each linked Feature
Flag a ramp locks, as a gate. A refused start returns the
blocking ones in `gates`.
type: array
items:
$ref: '#/components/schemas/gates'
required:
- checklistItems
- status
- gates
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/experiments/exp_abc123/start-checklist/manual/complete'
\
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"keys":["Stakeholder sign-off","QA complete"]}'
/v1/experiments/{id}/stop:
post:
operationId: postExperimentStop
summary: Stop an experiment
tags:
- experiments
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
results:
description: The experiment conclusion status.
type: string
enum:
- dnf
- won
- lost
- inconclusive
enableTemporaryRollout:
description: >-
If true, include this stopped experiment in SDK payload and
force the release variation (`releasedVariationId`) to all
traffic.
type: boolean
releasedVariationId:
description: >-
Required if enableTemporaryRollout is true. Variation ID
(e.g. var_abc123) to release to 100% of traffic eligible for
this experiment.
type: string
winnerVariationId:
description: >-
Variation ID (e.g. var_abc123) of the winning variation.
Used only as metadata. Required if results is 'won' and
there are multiple test variations. Otherwise, defaults to
the test variation when results is 'won' and to the baseline
variation for other results.
type: string
analysis:
description: >-
Optional markdown summary displayed on the experiment
results page.
type: string
reason:
description: >-
Optional reason for ending the phase stored on the latest
phase metadata.
type: string
dateEnded:
description: >-
Optional ISO datetime for ending the latest phase. Defaults
to the current date and time.
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:
- results
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
experiment:
$ref: '#/components/schemas/ExperimentWithEnhancedStatus'
required:
- experiment
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
'409':
description: Conflict
content:
application/json:
schema:
type: object
description: Resource is not in a valid status for this operation
properties:
message:
type: string
code:
type: string
enum:
- invalid_status
details:
$ref: '#/components/schemas/ApiErrorInvalidStatusDetails'
required:
- message
- code
- details
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/experiments/exp_abc123/stop' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"results":"won","releasedVariationId":"var_treatment","winnerVariationId":"var_treatment","enableTemporaryRollout":true,"analysis":"Reached desired sample size with statistically significant positive lift; shipping treatment"}'
/v1/experiments/{id}/schedule:
put:
operationId: putExperimentSchedule
summary: Set an experiment's schedule and shipping automation
description: >-
Full-replace of the experiment's scheduled start/end and
end-of-experiment shipping automation. The body is the complete desired
state: any omitted field is cleared (omit `startAt` to remove a
scheduled start; send an empty body to clear the whole schedule).
Provide either `stopAt` or `stopAfter`, not both; a relative `stopAfter`
resolves to a concrete stop when the experiment starts. Setting a
scheduled end (`stopAt` or `stopAfter`) requires a `scheduledStopPlan`
(any mode, including `notify`). The scheduled end must be in the future:
a `stopAt` (or a `stopAfter` that resolves) in the past is rejected —
including one whose end date has already passed and been acted on, so
changing the plan after a soft end requires committing to a new end
date. Auto-ship shipping requires the Decision Framework.
tags:
- experiments
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
startAt:
description: >-
ISO datetime when the experiment should start; must be in
the future. Omit to clear a scheduled start. Staging still
happens via POST /experiments/{id}/start.
format: date-time
type: string
stopAt:
description: Absolute ISO datetime to stop the experiment.
format: date-time
type: string
stopAfter:
description: >-
Deferred relative end, resolved to a concrete stop at the
experiment's actual start (or now, if already running).
type: object
properties:
value:
type: integer
exclusiveMinimum: 0
unit:
type: string
enum:
- hours
- days
required:
- value
- unit
additionalProperties: false
scheduledStopPlan:
description: >-
End-of-experiment automation. Required whenever a `stopAt`
or `stopAfter` is set (any mode, including `notify`).
$ref: '#/components/schemas/ScheduledStopPlan'
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
experiment:
$ref: '#/components/schemas/ExperimentWithEnhancedStatus'
warnings:
type: array
items:
type: string
required:
- experiment
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
'409':
description: Conflict
content:
application/json:
schema:
type: object
description: Resource is not in a valid status for this operation
properties:
message:
type: string
code:
type: string
enum:
- invalid_status
details:
$ref: '#/components/schemas/ApiErrorInvalidStatusDetails'
required:
- message
- code
- details
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/experiments/exp_abc123/schedule' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"startAt":"2026-08-01T00:00:00Z","stopAfter":{"value":14,"unit":"days"},"scheduledStopPlan":{"mode":"auto-ship","tiebreakerMetricId":"met_revenue","fallback":"force-ship","fallbackVariationId":"var_treatment"}}'
/v1/experiments/{id}/modify-temporary-rollout:
post:
operationId: postExperimentModifyTemporaryRollout
summary: Modify temporary rollout status for a stopped experiment
tags:
- experiments
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
enableTemporaryRollout:
description: >-
If true, keep the stopped experiment in SDK payload and
force traffic to the winner variation. If false, end
temporary rollout and remove from SDK payload.
type: boolean
releasedVariationId:
description: >-
Variation ID (e.g. var_abc123) to release to 100% of traffic
eligible for this experiment. Required if
enableTemporaryRollout is true.
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:
- enableTemporaryRollout
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
experiment:
$ref: '#/components/schemas/ExperimentWithEnhancedStatus'
required:
- experiment
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
'409':
description: Conflict
content:
application/json:
schema:
type: object
description: Resource is not in a valid status for this operation
properties:
message:
type: string
code:
type: string
enum:
- invalid_status
details:
$ref: '#/components/schemas/ApiErrorInvalidStatusDetails'
required:
- message
- code
- details
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/experiments/exp_abc123/modify-temporary-rollout'
\
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"enableTemporaryRollout":false}'
/v1/experiments/{id}/snapshot:
post:
operationId: postExperimentSnapshot
summary: Create Experiment Snapshot
tags:
- experiments
- snapshots
parameters:
- name: id
in: path
required: true
description: The experiment id of the experiment to update
schema:
description: The experiment id of the experiment to update
type: string
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
triggeredBy:
description: >-
Set to "schedule" if you want this request to trigger
notifications and other events as if it were a scheduled
update. Defaults to manual.
type: string
enum:
- manual
- schedule
dimension:
description: >-
Dimension to break results down by. For Unit Dimensions, use
the dimension id (e.g. "dim_abc123"). For Experiment
Dimensions, use "exp:" (e.g. "exp:country").
Built-in pre-exposure dimensions include "pre:date" and,
when configured, "pre:activation". Use "cutoff:" (e.g. "cutoff:2026-01-15T00:12:00.000Z") to split
units by whether they were first exposed before or after the
cutoff; it must fall within the phase dates. Use
"combo:::" (e.g.
"combo:exp:country::dim_abc123") to break down by the
intersection of two dimensions, each an Experiment Dimension
or Unit Dimension id; values beyond the top 20 combined
slices are merged into "(other)". Omit this field to create
a standard snapshot.
type: string
phase:
description: >-
Zero-based phase index to snapshot, where 0 is the first
experiment phase. Defaults to the latest phase.
type: integer
minimum: 0
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
snapshot:
$ref: '#/components/schemas/snapshot'
required:
- snapshot
additionalProperties: false
'409':
description: Conflict
content:
application/json:
schema:
oneOf:
- type: object
description: >-
The Incremental Pipeline needs a Full Refresh of Overall
Results before this request can be served
properties:
message:
type: string
code:
type: string
enum:
- requires_full_refresh
details:
$ref: >-
#/components/schemas/ApiErrorRequiresFullRefreshDetails
required:
- message
- code
- details
- type: object
description: >-
The requested dimension was already computed from the
latest Overall Results
properties:
message:
type: string
code:
type: string
enum:
- dimension_already_up_to_date
details:
$ref: >-
#/components/schemas/ApiErrorDimensionAlreadyUpToDateDetails
required:
- message
- code
- details
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/experiments/{id}/snapshot' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"triggeredBy":"schedule"}'
/v1/experiments/{id}/variation/{variationId}/screenshot/upload:
post:
operationId: postVariationImageUpload
summary: Upload a variation screenshot
tags:
- experiments
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/variationId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
screenshot:
contentEncoding: base64
description: Base64-encoded screenshot data
type: string
contentType:
description: MIME type of the screenshot
type: string
enum:
- image/png
- image/jpeg
- image/gif
description:
description: Optional description for the screenshot
type: string
required:
- screenshot
- contentType
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
screenshot:
$ref: '#/components/schemas/screenshot'
required:
- screenshot
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/experiments/{id}/variation/{variationId}/screenshot/upload'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/experiments/{id}/variation/{variationId}/screenshot:
delete:
operationId: deleteVariationScreenshot
summary: Delete a variation screenshot
tags:
- experiments
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/variationId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
path:
description: The screenshot path/URL to delete (from upload response)
type: string
required:
- path
additionalProperties: false
responses:
'200':
description: Screenshot deleted successfully
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/experiments/{id}/variation/{variationId}/screenshot'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/experiment-names:
get:
operationId: getExperimentNames
summary: Get a list of experiments with names and ids
tags:
- experiments
parameters:
- $ref: '#/components/parameters/projectId'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
experiments:
type: array
items:
$ref: '#/components/schemas/experiments'
required:
- experiments
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/experiment-names' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/experiments/{id}/comment:
post:
operationId: postExperimentComment
summary: Post a comment on an experiment
description: >-
Adds a new comment to an experiment's discussion thread, credited to the
person behind the request. Needs a personal access token, or an
organization API key that assumes a named member's role.
tags:
- experiments
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
comment:
type: string
minLength: 1
required:
- comment
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
status:
type: number
required:
- status
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/experiments/exp_abc123/comment' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"comment":"This looks good to ship."}'
/v1/experiments/{id}/visual-changesets:
get:
operationId: listVisualChangesets
summary: Get all visual changesets
tags:
- visual-changesets
parameters:
- name: id
in: path
required: true
description: The experiment id the visual changesets belong to
schema:
description: The experiment id the visual changesets belong to
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
visualChangesets:
type: array
items:
$ref: '#/components/schemas/VisualChangeset'
required:
- visualChangesets
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/experiments/abc123/visual-changesets'
\
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postVisualChangesets
summary: Create a visual changeset for an experiment
tags:
- visual-changesets
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
editorUrl:
description: >-
URL of the page opened in the visual editor when creating
this changeset
type: string
urlPatterns:
description: >-
URL patterns that determine which pages this visual
changeset applies to
type: array
items:
type: object
properties:
include:
type: boolean
type:
type: string
enum:
- simple
- regex
pattern:
type: string
required:
- type
- pattern
additionalProperties: {}
required:
- editorUrl
- urlPatterns
additionalProperties: {}
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
visualChangeset:
$ref: '#/components/schemas/VisualChangeset'
required:
- visualChangeset
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/experiments/abc123/visual-changesets'
\
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"editorUrl":"https://example.com/","urlPatterns":[{"type":"simple","pattern":"/","include":true}]}'
/v1/contextual-bandits/{id}/current:
get:
operationId: getContextualBanditCurrentWeights
summary: Get current Contextual Bandit leaf weights and latest event
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: The Contextual Bandit id
schema:
description: The Contextual Bandit id
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
currentLeafWeights:
type: array
items:
$ref: '#/components/schemas/currentLeafWeights'
latestEvent:
anyOf:
- type: object
properties:
id:
type: string
contextualBandit:
type: string
snapshotId:
type: string
weightsWereUpdated:
type: boolean
degreesOfFreedom:
type: integer
minimum: 0
dateCreated:
type: string
required:
- id
- contextualBandit
- snapshotId
- weightsWereUpdated
- dateCreated
additionalProperties: false
- type: 'null'
required:
- latestEvent
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/contextual-bandits/{id}/current' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/contextual-bandits/{id}/snapshots:
get:
operationId: listContextualBanditSnapshots
summary: List Contextual Bandit snapshots
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: The Contextual Bandit id
schema:
description: The Contextual Bandit id
type: string
- name: limit
in: query
description: ''
schema:
type: integer
exclusiveMinimum: 0
maximum: 100
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
snapshots:
type: array
items:
$ref: '#/components/schemas/snapshots'
required:
- snapshots
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/contextual-bandits/{id}/snapshots'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/contextual-bandits/{id}/snapshots/{snapshotId}:
get:
operationId: getContextualBanditSnapshot
summary: Get a single Contextual Bandit snapshot
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: The Contextual Bandit id
schema:
description: The Contextual Bandit id
type: string
- $ref: '#/components/parameters/snapshotId'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
snapshot:
$ref: '#/components/schemas/snapshots'
required:
- snapshot
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/contextual-bandits/{id}/snapshots/{snapshotId}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/contextual-bandits/{id}/events:
get:
operationId: listContextualBanditEvents
summary: List Contextual Bandit weight-update events
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: The Contextual Bandit id
schema:
description: The Contextual Bandit id
type: string
- name: limit
in: query
description: ''
schema:
type: integer
exclusiveMinimum: 0
maximum: 100
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
events:
type: array
items:
$ref: '#/components/schemas/events'
required:
- events
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/contextual-bandits/{id}/events' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/contextual-bandits/{id}/events/{eventId}:
get:
operationId: getContextualBanditEvent
summary: Get a single Contextual Bandit weight-update event
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: The Contextual Bandit id
schema:
description: The Contextual Bandit id
type: string
- $ref: '#/components/parameters/eventId'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
event:
$ref: '#/components/schemas/events'
required:
- event
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/contextual-bandits/{id}/events/{eventId}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/contextual-bandits/{id}/results:
get:
operationId: getContextualBanditResults
summary: Get latest Contextual Bandit results
description: >-
Returns the latest contextual-bandit stats engine output (per-context
responses tagged with their leaf, the per-leaf targeting conditions, and
per-leaf aggregated stats), the overall (marginal) variation weights
across all contexts, the health checks (traffic, SRM, multiple
exposures) computed by that same run, and the status of the most recent
snapshot run for the contextual bandit. Same payload the GrowthBook UI
uses to render the contextual bandit results and health tabs.
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: The Contextual Bandit id
schema:
description: The Contextual Bandit id
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
contextualBanditSnapshot:
anyOf:
- type: object
properties:
attributes:
type: array
items:
type: string
responses:
type: array
items: {}
leaf_map:
type: array
items: {}
leaf_stats:
type: array
items: {}
sse_trajectory:
type: array
items: {}
bic_trajectory:
type: array
items: {}
required:
- attributes
- responses
additionalProperties: false
- type: 'null'
overallWeights:
anyOf:
- type: array
items:
type: object
properties:
variationId:
type: string
weight:
anyOf:
- type: number
- type: 'null'
required:
- variationId
- weight
additionalProperties: false
- type: 'null'
results:
anyOf:
- type: object
properties:
attributes:
type: array
items:
type: string
sseTrajectory:
type: array
items:
type: object
properties:
numSplits:
type: integer
minimum: 0
totalSse:
type: number
split:
type: object
properties:
leafClauses:
type: array
items:
type: object
properties:
attribute:
type: string
levels:
type: array
items:
type: string
operator:
type: string
enum:
- in
- not in
required:
- attribute
- levels
- operator
additionalProperties: false
attribute:
type: string
leftLevels:
type: array
items:
type: string
rightLevels:
type: array
items:
type: string
required:
- leafClauses
- attribute
- leftLevels
- rightLevels
additionalProperties: false
required:
- numSplits
- totalSse
additionalProperties: false
overall:
type: object
properties:
variations:
type: array
items:
type: object
properties:
variationId:
type: string
variationName:
type: string
weight:
anyOf:
- type: number
- type: 'null'
mean:
anyOf:
- type: number
- type: 'null'
users:
anyOf:
- type: number
- type: 'null'
required:
- variationId
- weight
- mean
- users
additionalProperties: false
required:
- variations
additionalProperties: false
leaves:
type: array
items:
type: object
properties:
leafId:
type: integer
updateMessage:
anyOf:
- type: string
- type: 'null'
error:
anyOf:
- type: string
- type: 'null'
clauses:
type: array
items:
type: object
properties:
attribute:
type: string
levels:
type: array
items:
type: string
operator:
type: string
enum:
- in
- not in
required:
- attribute
- levels
- operator
additionalProperties: false
variations:
type: array
items:
type: object
properties:
variationId:
type: string
variationName:
type: string
weight:
anyOf:
- type: number
- type: 'null'
bestArmProbability:
anyOf:
- type: number
- type: 'null'
users:
anyOf:
- type: number
- type: 'null'
mean:
anyOf:
- type: number
- type: 'null'
variance:
anyOf:
- type: number
- type: 'null'
required:
- variationId
- weight
- bestArmProbability
- users
- mean
- variance
additionalProperties: false
contexts:
type: array
items:
type: object
properties:
attributes:
type: object
propertyNames:
type: string
additionalProperties:
type: string
variations:
type: array
items:
type: object
properties:
variationId:
type: string
variationName:
type: string
users:
anyOf:
- type: number
- type: 'null'
mean:
anyOf:
- type: number
- type: 'null'
variance:
anyOf:
- type: number
- type: 'null'
required:
- variationId
- users
- mean
- variance
additionalProperties: false
required:
- attributes
- variations
additionalProperties: false
required:
- leafId
- updateMessage
- error
- clauses
- variations
- contexts
additionalProperties: false
snapshotId:
type: string
dateCreated:
type: string
health:
anyOf:
- type: object
properties:
variations:
type: array
items:
type: object
properties:
variationId:
type: string
variationName:
type: string
weight:
type: number
required:
- variationId
- weight
additionalProperties: false
traffic:
anyOf:
- type: object
properties:
overall:
type: object
properties:
name:
type: string
srm:
type: number
variationUnits:
type: array
items:
type: number
required:
- name
- srm
- variationUnits
additionalProperties: false
dimension:
type: object
propertyNames:
type: string
additionalProperties:
type: array
items:
type: object
properties:
name:
type: string
srm:
type: number
variationUnits:
type: array
items:
type: number
required:
- name
- srm
- variationUnits
additionalProperties: false
error:
type: string
required:
- overall
- dimension
additionalProperties: false
- type: 'null'
srm:
anyOf:
- type: object
properties:
statistic:
type: number
pValue:
type: number
degreesOfFreedom:
type: integer
minimum: 0
latestPeriod:
type: object
properties:
banditVersion:
type: string
leaves:
type: array
items:
type: object
properties:
leafId:
type: string
observed:
type: array
items:
type: number
expected:
type: array
items:
type: number
required:
- leafId
- observed
- expected
additionalProperties: false
required:
- banditVersion
- leaves
additionalProperties: false
required:
- statistic
- pValue
- degreesOfFreedom
additionalProperties: false
- type: 'null'
multipleExposures:
anyOf:
- type: number
- type: 'null'
required:
- variations
- traffic
- srm
- multipleExposures
additionalProperties: false
- type: 'null'
required:
- attributes
- sseTrajectory
- overall
- leaves
- snapshotId
- dateCreated
- health
additionalProperties: false
- type: 'null'
latest:
anyOf:
- type: object
properties:
id:
type: string
status:
type: string
enum:
- running
- success
- error
error:
type: string
queries:
type: array
items:
type: object
properties:
query:
type: string
status:
type: string
enum:
- queued
- running
- failed
- partially-succeeded
- succeeded
name:
type: string
required:
- query
- status
- name
additionalProperties: false
runStarted:
anyOf:
- type: string
- type: 'null'
dateCreated:
type: string
multipleExposures:
type: number
type:
type: string
triggeredBy:
type: string
required:
- id
- status
- error
- queries
- runStarted
- dateCreated
- multipleExposures
- type
- triggeredBy
additionalProperties: false
- type: 'null'
required:
- contextualBanditSnapshot
- overallWeights
- results
- latest
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/contextual-bandits/{id}/results' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/contextual-bandits/{id}/status:
get:
operationId: getContextualBanditStatus
summary: Get Contextual Bandit run status
description: >-
Returns just the status of the most recent snapshot run for the
contextual bandit (id, status, queries, timestamps). A lightweight
alternative to the full results endpoint, intended for polling while a
run is in progress.
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: The Contextual Bandit id
schema:
description: The Contextual Bandit id
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
latest:
anyOf:
- type: object
properties:
id:
type: string
status:
type: string
enum:
- running
- success
- error
error:
type: string
queries:
type: array
items:
type: object
properties:
query:
type: string
status:
type: string
enum:
- queued
- running
- failed
- partially-succeeded
- succeeded
name:
type: string
required:
- query
- status
- name
additionalProperties: false
runStarted:
anyOf:
- type: string
- type: 'null'
dateCreated:
type: string
multipleExposures:
type: number
type:
type: string
triggeredBy:
type: string
required:
- id
- status
- error
- queries
- runStarted
- dateCreated
- multipleExposures
- type
- triggeredBy
additionalProperties: false
- type: 'null'
required:
- latest
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/contextual-bandits/{id}/status' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/contextual-bandits/{id}/linked-features:
get:
operationId: getContextualBanditLinkedFeatures
summary: Get features linked to a Contextual Bandit
description: >-
Returns the features that reference this contextual bandit via a
`contextual-bandit-ref` rule, enriched with each feature's live/draft
state, per-environment rule state, and variation values. Same payload
the GrowthBook UI uses to render the Linked Features section.
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: The Contextual Bandit id
schema:
description: The Contextual Bandit id
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
linkedFeatures:
type: array
items: {}
environments:
type: array
items:
type: string
required:
- linkedFeatures
- environments
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/contextual-bandits/{id}/linked-features'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/contextual-bandits/{id}/linked-feature/{featureId}:
post:
operationId: addContextualBanditLinkedFeature
summary: Link a feature to a Contextual Bandit
description: >-
Adds a `contextual-bandit-ref` rule to the bottom of the feature's rule
list and links the feature to this contextual bandit. The rule lands in
a draft revision that auto-publishes when the contextual bandit starts,
unless `autoPublish` is set. Targeting (condition, Saved Groups,
prerequisites, coverage) is inherited from the contextual bandit and
cannot be set on the rule.
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: The Contextual Bandit id
schema:
description: The Contextual Bandit id
type: string
- name: featureId
in: path
required: true
description: The linked feature id
schema:
description: The linked feature id
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
variations:
description: >-
One entry per Contextual Bandit variation. Every variation
must be covered exactly once.
minItems: 1
type: array
items:
type: object
properties:
variationId:
description: Id of the Contextual Bandit variation.
type: string
value:
description: Feature value served for this variation.
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:
- variationId
- value
additionalProperties: false
description:
type: string
enabled:
type: boolean
allEnvironments:
description: Apply the rule in every environment. Defaults to true.
type: boolean
environments:
description: Environments to apply the rule in when not all.
type: array
items:
type: string
allProjects:
type: boolean
projects:
type: array
items:
type: string
autoPublish:
description: >-
Publish the resulting revision immediately instead of
leaving it as a draft.
type: boolean
allowUnscopedRules:
description: >-
When the organization requires rules to target specific
environments or Projects, set to true to save a rule that
applies to All Environments and All Projects. 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
draftVersion:
description: >-
Add the rule to this existing draft revision instead of
starting a new one.
type: integer
required:
- variations
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
featureId:
type: string
ruleId:
type: string
revisionVersion:
type: number
published:
type: boolean
required:
- featureId
- ruleId
- revisionVersion
- published
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
'422':
description: Error
content:
application/json:
schema:
type: object
description: >-
A rule applies to All Environments and All Projects, which the
organization doesn't allow without `allowUnscopedRules`
properties:
message:
type: string
code:
type: string
enum:
- unscoped_rule
details:
$ref: '#/components/schemas/ApiErrorUnscopedRuleDetails'
required:
- message
- code
- details
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/contextual-bandits/{id}/linked-feature/{featureId}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: updateContextualBanditLinkedFeature
summary: Replace a Contextual Bandit's rule on a linked feature
description: >-
Replaces every `contextual-bandit-ref` rule pointing at this contextual
bandit on the feature, keeping each rule's id and position in the rule
list. Every field is replaced, so omitted optional fields revert to
their defaults. Returns a 400 when the feature has no such rule on the
target revision, or when it has several that are not identical to each
other. The change lands in a draft revision that auto-publishes when the
contextual bandit starts, unless `autoPublish` is set. Targeting
(condition, Saved Groups, prerequisites, coverage) is inherited from the
contextual bandit and cannot be set on the rule.
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: The Contextual Bandit id
schema:
description: The Contextual Bandit id
type: string
- name: featureId
in: path
required: true
description: The linked feature id
schema:
description: The linked feature id
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
variations:
description: >-
One entry per Contextual Bandit variation. Every variation
must be covered exactly once.
minItems: 1
type: array
items:
type: object
properties:
variationId:
description: Id of the Contextual Bandit variation.
type: string
value:
description: Feature value served for this variation.
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:
- variationId
- value
additionalProperties: false
description:
type: string
enabled:
type: boolean
allEnvironments:
description: Apply the rule in every environment. Defaults to true.
type: boolean
environments:
description: Environments to apply the rule in when not all.
type: array
items:
type: string
allProjects:
type: boolean
projects:
type: array
items:
type: string
autoPublish:
description: >-
Publish the resulting revision immediately instead of
leaving it as a draft.
type: boolean
allowUnscopedRules:
description: >-
When the organization requires rules to target specific
environments or Projects, set to true to save a rule that
applies to All Environments and All Projects. 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
draftVersion:
description: >-
Update the rule on this existing draft revision instead of
starting a new one.
type: integer
required:
- variations
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
featureId:
type: string
ruleIds:
type: array
items:
type: string
revisionVersion:
type: number
published:
type: boolean
required:
- featureId
- ruleIds
- revisionVersion
- published
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
'422':
description: Error
content:
application/json:
schema:
type: object
description: >-
A rule applies to All Environments and All Projects, which the
organization doesn't allow without `allowUnscopedRules`
properties:
message:
type: string
code:
type: string
enum:
- unscoped_rule
details:
$ref: '#/components/schemas/ApiErrorUnscopedRuleDetails'
required:
- message
- code
- details
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/contextual-bandits/{id}/linked-feature/{featureId}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteContextualBanditLinkedFeature
summary: Unlink a feature from a Contextual Bandit
description: >-
Removes every `contextual-bandit-ref` rule pointing at this contextual
bandit from the feature and drops the feature from the bandit's
linked-feature list. The rule removal lands in a draft revision unless
`autoPublish` is set. When the feature has no such rule left, only the
linkage is cleared.
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: The Contextual Bandit id
schema:
description: The Contextual Bandit id
type: string
- name: featureId
in: path
required: true
description: The linked feature id
schema:
description: The linked feature id
type: string
- $ref: '#/components/parameters/autoPublish'
- $ref: '#/components/parameters/draftVersion'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
featureId:
type: string
removedRuleIds:
type: array
items:
type: string
revisionVersion:
anyOf:
- type: number
- type: 'null'
published:
type: boolean
required:
- featureId
- removedRuleIds
- revisionVersion
- published
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/contextual-bandits/{id}/linked-feature/{featureId}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/snapshots/{id}:
get:
operationId: getExperimentSnapshot
summary: Get an experiment snapshot status
tags:
- snapshots
parameters:
- name: id
in: path
required: true
description: The id of the requested resource (a snapshot ID, not experiment ID)
schema:
description: >-
The id of the requested resource (a snapshot ID, not experiment
ID)
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
snapshot:
$ref: '#/components/schemas/snapshot'
required:
- snapshot
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/snapshots/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/metrics:
get:
operationId: listMetrics
summary: Get all metrics
tags:
- metrics
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/projectId'
- $ref: '#/components/parameters/datasourceId'
- $ref: '#/components/parameters/includeArchived'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
metrics:
type: array
items:
$ref: '#/components/schemas/Metric'
required:
- metrics
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/metrics' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postMetric
summary: Create a single metric
tags:
- metrics
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
datasourceId:
description: ID for the [DataSource](#tag/DataSource_model)
type: string
managedBy:
description: >-
Where this metric must be managed from. If not set (empty
string), it can be managed from anywhere. If set to "api",
it can be managed via the API only.
type: string
enum:
- ''
- api
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
name:
description: >-
Short display name (e.g. `Purchases per user`). Put the
definition in `description`.
type: string
description:
description: Markdown. Put context here, not in the name.
type: string
maxLength: 10000
type:
description: >-
Type of metric. See [Metrics
documentation](/app/metrics/legacy)
type: string
enum:
- binomial
- count
- duration
- revenue
tags:
description: >-
Tags for filtering and grouping. Use these instead of
encoding groups in names.
type: array
items:
type: string
projects:
description: List of project IDs for projects that can access this metric
type: array
items:
type: string
archived:
type: boolean
behavior:
type: object
properties:
goal:
type: string
enum:
- increase
- decrease
cappingSettings:
description: Controls how outliers are handled
type: object
properties:
type:
anyOf:
- type: string
enum:
- none
- absolute
- percentile
- type: 'null'
value:
description: >-
When type is absolute, this is the absolute value.
When type is percentile, this is the percentile
value (from 0.0 to 1.0).
type: number
ignoreZeros:
description: >-
If true and capping is `percentile`, zeros will be
ignored when calculating the percentile.
type: boolean
required:
- type
additionalProperties: false
cap:
deprecated: true
description: >-
(deprecated, use cappingSettings instead) This should be
non-negative
type: number
minimum: 0
capping:
deprecated: true
description: >-
(deprecated, use cappingSettings instead) Used in
conjunction with `capValue` to set the capping
(winsorization). Do not specify or set to null for no
capping. "absolute" will cap user values at the
`capValue` if it is greater than 0. "percentile" will
cap user values at the percentile of user values in an
experiment using the `capValue` for the percentile, if
greater than 0.
If `behavior.capping` is
non-null, you must specify `behavior.capValue`.
anyOf:
- type: string
enum:
- absolute
- percentile
- type: 'null'
capValue:
deprecated: true
description: >-
(deprecated, use cappingSettings instead) This should be
non-negative.
Must specify `behavior.capping` when
setting `behavior.capValue`.
type: number
minimum: 0
windowSettings:
description: Controls the conversion window for the metric
type: object
properties:
type:
type: string
enum:
- none
- conversion
- lookback
delayHours:
deprecated: true
description: >-
Wait this many hours after experiment exposure
before counting conversions. Ignored if delayValue
is set.
type: number
delayValue:
description: >-
Wait this long after experiment exposure before
counting conversions.
type: number
delayUnit:
description: Default `hours`.
type: string
enum:
- minutes
- hours
- days
- weeks
windowValue:
type: number
windowUnit:
type: string
enum:
- minutes
- hours
- days
- weeks
required:
- type
additionalProperties: false
conversionWindowStart:
deprecated: true
description: >-
The start of a Conversion Window relative to the
exposure date, in hours. This is equivalent to the
[Conversion
Delay](/app/metrics/legacy/#conversion-delay).
Must specify both `behavior.conversionWindowStart` and
`behavior.conversionWindowEnd` or neither.
type: number
conversionWindowEnd:
deprecated: true
description: >-
The end of a [Conversion
Window](/app/metrics/legacy/#conversion-window) relative
to the exposure date, in hours. This is equivalent to
the [Conversion
Delay](/app/metrics/legacy/#conversion-delay) +
Conversion Window Hours settings in the UI. In other
words, if you want a 48 hour window starting after 24
hours, you would set conversionWindowStart to 24 and
conversionWindowEnd to 72 (24+48).
Must specify
both `behavior.conversionWindowStart` and
`behavior.conversionWindowEnd` or neither.
type: number
priorSettings:
description: >-
Controls the bayesian prior for the metric. If omitted,
organization defaults will be used.
type: object
properties:
override:
description: >-
If false, the organization default settings will be
used instead of the other settings in this object
type: boolean
proper:
description: >-
If true, the `mean` and `stddev` will be used,
otherwise we will use an improper flat prior.
type: boolean
mean:
description: >-
The mean of the prior distribution of relative
effects in proportion terms (e.g. 0.01 is 1%)
type: number
stddev:
description: >-
Must be > 0. The standard deviation of the prior
distribution of relative effects in proportion
terms.
type: number
exclusiveMinimum: 0
required:
- override
- proper
- mean
- stddev
additionalProperties: false
riskThresholdSuccess:
deprecated: true
description: No longer used. Accepted and ignored.
type: number
riskThresholdDanger:
deprecated: true
description: No longer used. Accepted and ignored.
type: number
minPercentChange:
description: >-
Minimum percent change to consider uplift significant,
as a proportion (e.g. put 0.005 for 0.5%)
type: number
minimum: 0
maxPercentChange:
description: >-
Maximum percent change to consider uplift significant,
as a proportion (e.g. put 0.5 for 50%)
type: number
minimum: 0
minSampleSize:
type: number
minimum: 0
targetMDE:
description: >-
The percentage change that you want to reliably detect
before ending an experiment, as a proportion (e.g. put
0.1 for 10%). This is used to estimate the "Days Left"
for running experiments.
type: number
minimum: 0
additionalProperties: false
sql:
description: >-
Preferred way to define SQL. Only one of `sql`, `sqlBuilder`
or `mixpanel` allowed, and at least one must be specified.
type: object
properties:
identifierTypes:
type: array
items:
type: string
conversionSQL:
type: string
userAggregationSQL:
description: >-
Custom user level aggregation for your metric (default:
`SUM(value)`)
type: string
denominatorMetricId:
description: >-
The metric ID for a [denominator metric for funnel and
ratio
metrics](/app/metrics/legacy/#denominator-ratio--funnel-metrics)
type: string
required:
- identifierTypes
- conversionSQL
additionalProperties: false
sqlBuilder:
description: >-
An alternative way to specify a SQL metric, rather than a
full query. Using `sql` is preferred to `sqlBuilder`. Only
one of `sql`, `sqlBuilder` or `mixpanel` allowed, and at
least one must be specified.
type: object
properties:
identifierTypeColumns:
type: array
items:
type: object
properties:
identifierType:
type: string
columnName:
type: string
required:
- identifierType
- columnName
additionalProperties: false
tableName:
type: string
valueColumnName:
type: string
timestampColumnName:
type: string
conditions:
type: array
items:
type: object
properties:
column:
type: string
operator:
type: string
value:
type: string
required:
- column
- operator
- value
additionalProperties: false
required:
- identifierTypeColumns
- tableName
- timestampColumnName
additionalProperties: false
mixpanel:
description: >-
Only use for MixPanel (non-SQL) Data Sources. Only one of
`sql`, `sqlBuilder` or `mixpanel` allowed, and at least one
must be specified.
type: object
properties:
eventName:
type: string
eventValue:
type: string
userAggregation:
type: string
conditions:
type: array
items:
type: object
properties:
property:
type: string
operator:
type: string
value:
type: string
required:
- property
- operator
- value
additionalProperties: false
required:
- eventName
- userAggregation
additionalProperties: false
required:
- datasourceId
- name
- type
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
metric:
$ref: '#/components/schemas/Metric'
required:
- metric
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/metrics' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/metrics/{id}:
get:
operationId: getMetric
summary: Get a single metric
tags:
- metrics
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
metric:
$ref: '#/components/schemas/Metric'
required:
- metric
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/metrics/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: putMetric
summary: Update a metric
tags:
- metrics
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
managedBy:
description: >-
Where this metric must be managed from. If not set (empty
string), it can be managed from anywhere. If set to "api",
it can be managed via the API only. Please note that we have
deprecated support for setting the managedBy property to
"admin". Your existing Legacy Metrics with this value will
continue to work, but we suggest migrating to Fact Metrics
instead.
type: string
enum:
- ''
- api
- admin
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
name:
description: >-
Short display name (e.g. `Purchases per user`). Put the
definition in `description`.
type: string
description:
description: Markdown. Put context here, not in the name.
type: string
maxLength: 10000
type:
description: >-
Type of metric. See [Metrics
documentation](/app/metrics/legacy)
type: string
enum:
- binomial
- count
- duration
- revenue
tags:
description: >-
Tags for filtering and grouping. Use these instead of
encoding groups in names.
type: array
items:
type: string
projects:
description: List of project IDs for projects that can access this metric
type: array
items:
type: string
archived:
type: boolean
behavior:
type: object
properties:
goal:
type: string
enum:
- increase
- decrease
cappingSettings:
description: Controls how outliers are handled
type: object
properties:
type:
anyOf:
- type: string
enum:
- none
- absolute
- percentile
- type: 'null'
value:
description: >-
When type is absolute, this is the absolute value.
When type is percentile, this is the percentile
value (from 0.0 to 1.0).
type: number
ignoreZeros:
description: >-
If true and capping is `percentile`, zeros will be
ignored when calculating the percentile.
type: boolean
required:
- type
additionalProperties: false
cap:
deprecated: true
description: >-
(deprecated, use cappingSettings instead) This should be
non-negative
type: number
minimum: 0
capping:
deprecated: true
description: >-
(deprecated, use cappingSettings instead) Used in
conjunction with `capValue` to set the capping
(winsorization). Do not specify or set to null for no
capping. "absolute" will cap user values at the
`capValue` if it is greater than 0. "percentile" will
cap user values at the percentile of user values in an
experiment using the `capValue` for the percentile, if
greater than 0.
If `behavior.capping` is
non-null, you must specify `behavior.capValue`.
anyOf:
- type: string
enum:
- absolute
- percentile
- type: 'null'
capValue:
deprecated: true
description: >-
(deprecated, use cappingSettings instead) This should be
non-negative.
Must specify `behavior.capping` when
setting `behavior.capValue`.
type: number
minimum: 0
windowSettings:
description: Controls the conversion window for the metric
type: object
properties:
type:
type: string
enum:
- none
- conversion
- lookback
delayHours:
deprecated: true
description: >-
Wait this many hours after experiment exposure
before counting conversions. Ignored if delayValue
is set.
type: number
delayValue:
description: >-
Wait this long after experiment exposure before
counting conversions.
type: number
delayUnit:
description: Default `hours`.
type: string
enum:
- minutes
- hours
- days
- weeks
windowValue:
type: number
windowUnit:
type: string
enum:
- minutes
- hours
- days
- weeks
required:
- type
additionalProperties: false
conversionWindowStart:
deprecated: true
description: >-
The start of a Conversion Window relative to the
exposure date, in hours. This is equivalent to the
[Conversion
Delay](/app/metrics/legacy/#conversion-delay).
Must specify both `behavior.conversionWindowStart` and
`behavior.conversionWindowEnd` or neither.
type: number
conversionWindowEnd:
deprecated: true
description: >-
The end of a [Conversion
Window](/app/metrics/legacy/#conversion-window) relative
to the exposure date, in hours. This is equivalent to
the [Conversion
Delay](/app/metrics/legacy/#conversion-delay) +
Conversion Window Hours settings in the UI. In other
words, if you want a 48 hour window starting after 24
hours, you would set conversionWindowStart to 24 and
conversionWindowEnd to 72 (24+48).
Must specify
both `behavior.conversionWindowStart` and
`behavior.conversionWindowEnd` or neither.
type: number
priorSettings:
description: >-
Controls the bayesian prior for the metric. If omitted,
organization defaults will be used.
type: object
properties:
override:
description: >-
If false, the organization default settings will be
used instead of the other settings in this object
type: boolean
proper:
description: >-
If true, the `mean` and `stddev` will be used,
otherwise we will use an improper flat prior.
type: boolean
mean:
description: >-
The mean of the prior distribution of relative
effects in proportion terms (e.g. 0.01 is 1%)
type: number
stddev:
description: >-
Must be > 0. The standard deviation of the prior
distribution of relative effects in proportion
terms.
type: number
exclusiveMinimum: 0
required:
- override
- proper
- mean
- stddev
additionalProperties: false
riskThresholdSuccess:
deprecated: true
description: No longer used. Accepted and ignored.
type: number
riskThresholdDanger:
deprecated: true
description: No longer used. Accepted and ignored.
type: number
minPercentChange:
description: >-
Minimum percent change to consider uplift significant,
as a proportion (e.g. put 0.005 for 0.5%)
type: number
minimum: 0
maxPercentChange:
description: >-
Maximum percent change to consider uplift significant,
as a proportion (e.g. put 0.5 for 50%)
type: number
minimum: 0
minSampleSize:
type: number
minimum: 0
targetMDE:
description: >-
The percentage change that you want to reliably detect
before ending an experiment, as a proportion (e.g. put
0.1 for 10%). This is used to estimate the "Days Left"
for running experiments.
type: number
minimum: 0
additionalProperties: false
sql:
description: >-
Preferred way to define SQL. Only one of `sql`, `sqlBuilder`
or `mixpanel` allowed.
type: object
properties:
identifierTypes:
type: array
items:
type: string
conversionSQL:
type: string
userAggregationSQL:
description: >-
Custom user level aggregation for your metric (default:
`SUM(value)`)
type: string
denominatorMetricId:
description: >-
The metric ID for a [denominator metric for funnel and
ratio
metrics](/app/metrics/legacy/#denominator-ratio--funnel-metrics)
type: string
additionalProperties: false
sqlBuilder:
description: >-
An alternative way to specify a SQL metric, rather than a
full query. Using `sql` is preferred to `sqlBuilder`. Only
one of `sql`, `sqlBuilder` or `mixpanel` allowed
type: object
properties:
identifierTypeColumns:
type: array
items:
type: object
properties:
identifierType:
type: string
columnName:
type: string
required:
- identifierType
- columnName
additionalProperties: false
tableName:
type: string
valueColumnName:
type: string
timestampColumnName:
type: string
conditions:
type: array
items:
type: object
properties:
column:
type: string
operator:
type: string
value:
type: string
required:
- column
- operator
- value
additionalProperties: false
additionalProperties: false
mixpanel:
description: >-
Only use for MixPanel (non-SQL) Data Sources. Only one of
`sql`, `sqlBuilder` or `mixpanel` allowed.
type: object
properties:
eventName:
type: string
eventValue:
type: string
userAggregation:
type: string
conditions:
type: array
items:
type: object
properties:
property:
type: string
operator:
type: string
value:
type: string
required:
- property
- operator
- value
additionalProperties: false
additionalProperties: false
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
updatedId:
type: string
required:
- updatedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X PUT 'https://api.growthbook.io/api/v1/metrics/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"name":"net revenue","description":"revenue minus lacroix spend"}'
delete:
operationId: deleteMetric
summary: Deletes a metric
tags:
- metrics
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X DELETE 'https://api.growthbook.io/api/v1/metrics/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/metrics/{id}/experiments:
get:
operationId: listMetricExperiments
summary: Get results for all experiments that use a metric
description: >-
Returns, for each experiment that uses the given metric (directly or via
a metric group), the per-variation results for that metric from the
latest snapshot. Supports the same filtering as the experiment list
views via a raw search string or structured query params. Note: at most
the 1000 most recent experiments using the metric are considered;
filters and pagination are applied within that set, so results may be
incomplete for metrics used by more than 1000 experiments.
tags:
- metrics
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/q'
- name: projectId
in: query
description: Filter by comma-separated project ids or names
schema:
description: Filter by comma-separated project ids or names
type: string
- $ref: '#/components/parameters/owner'
- name: status
in: query
description: Filter by comma-separated statuses (draft, running, stopped)
schema:
description: Filter by comma-separated statuses (draft, running, stopped)
type: string
- name: result
in: query
description: Filter by comma-separated results (won, lost, inconclusive, dnf)
schema:
description: Filter by comma-separated results (won, lost, inconclusive, dnf)
type: string
- $ref: '#/components/parameters/tag'
- $ref: '#/components/parameters/type'
- $ref: '#/components/parameters/bandits'
- $ref: '#/components/parameters/startDate'
- $ref: '#/components/parameters/endDate'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
experimentResults:
type: array
items:
$ref: '#/components/schemas/experimentResults'
required:
- experimentResults
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/metrics/met_abc123/experiments' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/usage/metrics:
get:
operationId: getMetricUsage
summary: Get metric usage across experiments
description: >
Returns usage information for one or more legacy or fact metrics,
showing which experiments use each metric
and some usage statistics. If a metric is part of a metric group, then
usage of that metric group counts as
usage of all metrics in the group. Warning: only includes experiments
that you have access to! If you do not have admin
access or read access to experiments across all projects, this endpoint
may not return the latest usage data across
all experiments.
tags:
- usage
parameters:
- name: ids
in: query
required: true
description: >-
List of comma-separated metric IDs (both fact and legacy) to get
usage for, e.g. ids=met_123,fact_456
schema:
description: >-
List of comma-separated metric IDs (both fact and legacy) to get
usage for, e.g. ids=met_123,fact_456
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
metricUsage:
type: array
items:
$ref: '#/components/schemas/MetricUsage'
required:
- metricUsage
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/usage/metrics' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/segments:
get:
operationId: listSegments
summary: Get all segments
tags:
- segments
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/datasourceId'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
segments:
type: array
items:
$ref: '#/components/schemas/Segment'
required:
- segments
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/segments' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postSegment
summary: Create a single segment
tags:
- segments
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name. Put details in `description`.
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
description:
description: Description of the segment
type: string
maxLength: 10000
datasourceId:
description: ID of the datasource this segment belongs to
type: string
identifierType:
description: Type of identifier (user, anonymous, etc.)
type: string
projects:
description: >-
List of project IDs for projects that can access this
segment
type: array
items:
type: string
managedBy:
description: >-
Where this Segment must be managed from. If not set (empty
string), it can be managed from anywhere.
type: string
enum:
- ''
- api
type:
description: >-
GrowthBook supports two types of Segments, SQL and FACT. SQL
segments are defined by a SQL query, and FACT segments are
defined by a fact table and filters.
type: string
enum:
- SQL
- FACT
query:
description: >-
SQL query that defines the Segment. This is required for SQL
segments.
type: string
factTableId:
description: >-
ID of the fact table this segment belongs to. This is
required for FACT segments.
type: string
filters:
description: >-
Optional array of fact table filter ids that can further
define the Fact Table based Segment.
type: array
items:
type: string
required:
- name
- datasourceId
- identifierType
- type
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
segment:
$ref: '#/components/schemas/Segment'
required:
- segment
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/segments' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"name":"Annual Subscribers","datasourceId":"ds_123abc","identifierType":"user_id","type":"SQL","query":"SELECT plan FROM subscribers WHERE plan = "}'
/v1/segments/{id}:
get:
operationId: getSegment
summary: Get a single segment
tags:
- segments
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
segment:
$ref: '#/components/schemas/Segment'
required:
- segment
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/segments/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: updateSegment
summary: Update a single segment
tags:
- segments
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name. Put details in `description`.
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
description:
description: Description of the segment
type: string
maxLength: 10000
datasourceId:
description: ID of the datasource this segment belongs to
type: string
identifierType:
description: Type of identifier (user, anonymous, etc.)
type: string
projects:
description: >-
List of project IDs for projects that can access this
segment
type: array
items:
type: string
managedBy:
description: >-
Where this Segment must be managed from. If not set (empty
string), it can be managed from anywhere.
type: string
enum:
- ''
- api
type:
description: >-
GrowthBook supports two types of Segments, SQL and FACT. SQL
segments are defined by a SQL query, and FACT segments are
defined by a fact table and filters.
type: string
enum:
- SQL
- FACT
query:
description: >-
SQL query that defines the Segment. This is required for SQL
segments.
type: string
factTableId:
description: >-
ID of the fact table this segment belongs to. This is
required for FACT segments.
type: string
filters:
description: >-
Optional array of fact table filter ids that can further
define the Fact Table based Segment.
type: array
items:
type: string
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
segment:
$ref: '#/components/schemas/Segment'
required:
- segment
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/segments/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"name":"User Region"}'
delete:
operationId: deleteSegment
summary: Deletes a single segment
tags:
- segments
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
description: The ID of the deleted segment
example: seg_123abc
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X DELETE 'https://api.growthbook.io/api/v1/segments/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/dimensions:
get:
operationId: listDimensions
summary: Get all dimensions
tags:
- dimensions
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/datasourceId'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
dimensions:
type: array
items:
$ref: '#/components/schemas/Dimension'
required:
- dimensions
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/dimensions' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postDimension
summary: Create a single dimension
tags:
- dimensions
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name. Put details in `description`.
type: string
description:
description: Description of the dimension
type: string
maxLength: 10000
owner:
description: >-
The userId or email address of the owner. If an email
address is provided, it will be used to look up the userId
of the matching organization member. If an ID is provided,
it will be validated as existing in the organization.
type: string
datasourceId:
description: ID of the datasource this dimension belongs to
type: string
identifierType:
description: Type of identifier (user, anonymous, etc.)
type: string
query:
description: SQL query or equivalent for the dimension
type: string
managedBy:
description: >-
Where this dimension must be managed from. If not set (empty
string), it can be managed from anywhere.
type: string
enum:
- ''
- api
required:
- name
- datasourceId
- identifierType
- query
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
dimension:
$ref: '#/components/schemas/Dimension'
required:
- dimension
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/dimensions' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"name":"User Country","datasourceId":"ds_123abc","identifierType":"user","query":"SELECT country FROM users"}'
/v1/dimensions/{id}:
get:
operationId: getDimension
summary: Get a single dimension
tags:
- dimensions
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
dimension:
$ref: '#/components/schemas/Dimension'
required:
- dimension
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/dimensions/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: updateDimension
summary: Update a single dimension
tags:
- dimensions
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name. Put details in `description`.
type: string
description:
description: Description of the dimension
type: string
maxLength: 10000
owner:
description: >-
The userId or email address of the owner. If an email
address is provided, it will be used to look up the userId
of the matching organization member. If an ID is provided,
it will be validated as existing in the organization.
type: string
datasourceId:
description: ID of the datasource this dimension belongs to
type: string
identifierType:
description: Type of identifier (user, anonymous, etc.)
type: string
query:
description: SQL query or equivalent for the dimension
type: string
managedBy:
description: >-
Where this dimension must be managed from. If not set (empty
string), it can be managed from anywhere.
type: string
enum:
- ''
- api
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
dimension:
$ref: '#/components/schemas/Dimension'
required:
- dimension
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/dimensions/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"name":"User Region"}'
delete:
operationId: deleteDimension
summary: Deletes a single dimension
tags:
- dimensions
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
description: The ID of the deleted dimension
example: dim_123abc
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE 'https://api.growthbook.io/api/v1/dimensions/abc123'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/projects:
get:
operationId: listProjects
summary: Get all projects
tags:
- projects
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
projects:
type: array
items:
$ref: '#/components/schemas/Project'
required:
- projects
additionalProperties: false
- type: object
properties:
limit:
type: integer
offset:
type: integer
count:
type: integer
total:
type: integer
hasMore:
type: boolean
nextOffset:
anyOf:
- type: integer
- type: 'null'
required:
- limit
- offset
- count
- total
- hasMore
- nextOffset
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/projects' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postProject
summary: Create a single project
tags:
- projects
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name. Put details in `description`.
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. When
omitted, it defaults to the requesting member: a personal
access token's owner, or the member an organization API key
assumes. An organization API key acting as itself leaves it
empty.
type: string
description:
description: Put context here, not in the name.
type: string
maxLength: 10000
publicId:
description: >-
URL-safe slug (lowercase letters, numbers, dashes).
Auto-generated from name if not provided.
type: string
settings:
description: >-
Project settings that, when set, override the organization
settings.
type: object
properties:
statsEngine:
description: Stats engine.
type: string
confidenceLevel:
description: >-
Bayesian chance-to-win threshold (stored as decimal,
e.g. 0.95).
type: number
pValueThreshold:
description: Frequentist p-value threshold (e.g. 0.05).
type: number
additionalProperties: false
restrictAccess:
description: >-
When true, only members with an explicit role on this
Project (directly or via a team) can access it. Members with
the manageTeam permission retain access. Requires a Pro or
Enterprise plan.
type: boolean
allowTargeting:
description: >-
Whether Feature Flags owned by other Projects may add this
Project to their Targeting Projects. Defaults to true.
Turning it off blocks new targeting (and All Projects);
existing targeting is kept.
type: boolean
required:
- name
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
project:
$ref: '#/components/schemas/Project'
required:
- project
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/projects' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"name":"My Project","description":"Super cool project"}'
/v1/projects/{id}:
get:
operationId: getProject
summary: Get a single project
tags:
- projects
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
project:
$ref: '#/components/schemas/Project'
required:
- project
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/projects/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: putProject
summary: Edit a single project
tags:
- projects
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name. Put details in `description`.
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
description:
description: Put context here, not in the name.
type: string
maxLength: 10000
publicId:
description: URL-safe slug (lowercase letters, numbers, dashes).
type: string
settings:
description: >-
Project settings that, when set, override the organization
settings.
type: object
properties:
statsEngine:
description: Stats engine.
type: string
confidenceLevel:
description: >-
Bayesian chance-to-win threshold (stored as decimal,
e.g. 0.95).
type: number
pValueThreshold:
description: Frequentist p-value threshold (e.g. 0.05).
type: number
additionalProperties: false
restrictAccess:
description: >-
When true, only members with an explicit role on this
Project (directly or via a team) can access it. Members with
the manageTeam permission retain access. Requires a Pro or
Enterprise plan.
type: boolean
allowTargeting:
description: >-
Whether Feature Flags owned by other Projects may add this
Project to their Targeting Projects. Defaults to true.
Turning it off blocks new targeting (and All Projects);
existing targeting is kept.
type: boolean
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
project:
$ref: '#/components/schemas/Project'
required:
- project
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X PUT 'https://api.growthbook.io/api/v1/projects/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"name":"My Subsidiary"}'
delete:
operationId: deleteProject
summary: Deletes a single project
tags:
- projects
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
description: The ID of the deleted project
example: prj__123abc
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X DELETE 'https://api.growthbook.io/api/v1/projects/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/environments:
get:
operationId: listEnvironments
summary: Get the organization's environments
tags:
- environments
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
environments:
type: array
items:
$ref: '#/components/schemas/Environment'
required:
- environments
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/environments' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postEnvironment
summary: Create a new environment
tags:
- environments
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
description: >-
Permanent ID, shown as the environment name (e.g.
`production`). Short lowercase slug.
type: string
description:
description: Put context here, not in the name.
type: string
toggleOnList:
description: Show on feature list page
type: boolean
defaultState:
description: Default state for new features
type: boolean
projects:
description: >-
Limits which Projects can use this environment. Omit to
allow all Projects.
type: array
items:
type: string
parent:
description: >-
An environment that the new environment should inherit
feature rules from. Requires an enterprise license
type: string
required:
- id
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
environment:
$ref: '#/components/schemas/Environment'
required:
- environment
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/environments' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"id":"new-env","description":"My new environment"}'
/v1/environments/{id}:
put:
operationId: putEnvironment
summary: Update an environment
tags:
- environments
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
description:
description: Put context here, not in the name.
type: string
toggleOnList:
description: Show on feature list page
type: boolean
defaultState:
description: Default state for new features
type: boolean
projects:
description: >-
Limits which Projects can use this environment. Omit to keep
the current list; send `[]` to allow all Projects.
type: array
items:
type: string
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
environment:
$ref: '#/components/schemas/Environment'
required:
- environment
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X PUT 'https://api.growthbook.io/api/v1/environments/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"description":"My updated environment"}'
delete:
operationId: deleteEnvironment
summary: Deletes a single environment
tags:
- environments
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/environments/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/attributes:
get:
operationId: listAttributes
summary: Get the organization's attributes
tags:
- attributes
parameters:
- name: projectId
in: query
description: >-
Filter to attributes available in this project — includes org-wide
attributes (no project restriction) and attributes explicitly scoped
to this project.
schema:
description: >-
Filter to attributes available in this project — includes org-wide
attributes (no project restriction) and attributes explicitly
scoped to this project.
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
attributes:
type: array
items:
$ref: '#/components/schemas/Attribute'
required:
- attributes
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/attributes' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postAttribute
summary: Create a new attribute
tags:
- attributes
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
property:
description: >-
Attribute name exactly as your SDK passes it (e.g.
`userId`). The API can't rename it, and renaming it in the
UI doesn't update SDK code or targeting conditions.
type: string
datatype:
description: The attribute datatype
type: string
enum:
- boolean
- string
- number
- secureString
- enum
- string[]
- number[]
- secureString[]
description:
description: Markdown. Put context here, not in the name.
type: string
archived:
description: The attribute is archived
type: boolean
hashAttribute:
description: Shall the attribute be hashed
type: boolean
enum:
description: >-
Comma-separated list of allowed values. Required for the
'enum' datatype. For array datatypes (string[], number[],
secureString[]) it optionally restricts the list to these
values. Ignored for all other datatypes.
type: string
format:
description: The attribute's format
type: string
enum:
- ''
- version
- date
- isoCountryCode
projects:
description: >-
Project IDs that can use this. An empty list means all
Projects. Projects control access and availability, so don't
use them as labels.
type: array
items:
type: string
tags:
description: >-
Tags for filtering and grouping. Use these instead of
encoding groups in names.
type: array
items:
type: string
customFields:
description: >-
Values for the organization's attribute custom fields, keyed
by field id
type: object
propertyNames:
type: string
additionalProperties:
type: string
required:
- property
- datatype
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
attribute:
$ref: '#/components/schemas/Attribute'
required:
- attribute
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/attributes' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"property":"foo","datatype":"boolean","description":"My new attribute"}'
/v1/attributes/{property}:
put:
operationId: putAttribute
summary: Update an attribute
tags:
- attributes
parameters:
- $ref: '#/components/parameters/property'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
datatype:
description: The attribute datatype
type: string
enum:
- boolean
- string
- number
- secureString
- enum
- string[]
- number[]
- secureString[]
description:
description: Markdown. Put context here, not in the name.
type: string
archived:
description: The attribute is archived
type: boolean
hashAttribute:
description: Shall the attribute be hashed
type: boolean
enum:
description: >-
Comma-separated list of allowed values. Required for the
'enum' datatype. For array datatypes (string[], number[],
secureString[]) it optionally restricts the list to these
values. Ignored for all other datatypes.
type: string
format:
description: The attribute's format
type: string
enum:
- ''
- version
- date
- isoCountryCode
projects:
description: >-
Project IDs that can use this. An empty list means all
Projects. Projects control access and availability, so don't
use them as labels.
type: array
items:
type: string
tags:
description: >-
Tags for filtering and grouping. Use these instead of
encoding groups in names.
type: array
items:
type: string
customFields:
description: >-
Values for the organization's attribute custom fields, keyed
by field id
type: object
propertyNames:
type: string
additionalProperties:
type: string
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
attribute:
$ref: '#/components/schemas/Attribute'
required:
- attribute
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X PUT 'https://api.growthbook.io/api/v1/attributes/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"description":"My updated attribute"}'
delete:
operationId: deleteAttribute
summary: Deletes a single attribute
tags:
- attributes
parameters:
- $ref: '#/components/parameters/property'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedProperty:
type: string
required:
- deletedProperty
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE 'https://api.growthbook.io/api/v1/attributes/abc123'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/sdk-connections:
get:
operationId: listSdkConnections
summary: Get all sdk connections
tags:
- sdk-connections
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/projectId'
- $ref: '#/components/parameters/withProxy'
- $ref: '#/components/parameters/multiOrg'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
connections:
type: array
items:
$ref: '#/components/schemas/SdkConnection'
required:
- connections
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/sdk-connections' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postSdkConnection
summary: Create a single sdk connection
tags:
- sdk-connections
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: >-
Short display name, usually app and platform (e.g. `Web
app`).
type: string
language:
type: string
sdkVersion:
type: string
environment:
type: string
projects:
type: array
items:
type: string
encryptPayload:
type: boolean
includeVisualExperiments:
type: boolean
includeDraftExperiments:
type: boolean
includeDraftExperimentRefs:
description: >-
When true, experiment-ref rules linked to draft experiments
are included in feature definitions. Off by default.
type: boolean
includeExperimentNames:
type: boolean
includeRedirectExperiments:
type: boolean
includeRuleIds:
type: boolean
includeProjectIdInMetadata:
type: boolean
includeCustomFieldsInMetadata:
type: boolean
allowedCustomFieldsInMetadata:
type: array
items:
type: string
includeTagsInMetadata:
type: boolean
includeExperimentScheduleInMetadata:
type: boolean
proxyEnabled:
type: boolean
proxyHost:
type: string
hashSecureAttributes:
type: boolean
remoteEvalEnabled:
type: boolean
savedGroupReferencesEnabled:
description: Deprecated. Use `savedGroupFormat`.
type: boolean
savedGroupFormat:
type: string
enum:
- inline
- referencesV1
- referencesV2
includeReferencedPrerequisites:
description: >-
Carry prerequisite Feature Flags into this payload even when
they target other Projects. Defaults to true for new
connections.
type: boolean
required:
- name
- language
- environment
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
sdkConnection:
$ref: '#/components/schemas/SdkConnection'
required:
- sdkConnection
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/sdk-connections' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/sdk-connections/{id}:
get:
operationId: getSdkConnection
summary: Get a single sdk connection
tags:
- sdk-connections
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
sdkConnection:
$ref: '#/components/schemas/SdkConnection'
required:
- sdkConnection
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/sdk-connections/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: putSdkConnection
summary: Update a single sdk connection
tags:
- sdk-connections
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: >-
Short display name, usually app and platform (e.g. `Web
app`).
type: string
language:
type: string
sdkVersion:
type: string
environment:
type: string
projects:
type: array
items:
type: string
encryptPayload:
type: boolean
includeVisualExperiments:
type: boolean
includeDraftExperiments:
type: boolean
includeDraftExperimentRefs:
description: >-
When true, experiment-ref rules linked to draft experiments
are included in feature definitions. Off by default.
type: boolean
includeExperimentNames:
type: boolean
includeRedirectExperiments:
type: boolean
includeRuleIds:
type: boolean
includeProjectIdInMetadata:
type: boolean
includeCustomFieldsInMetadata:
type: boolean
allowedCustomFieldsInMetadata:
type: array
items:
type: string
includeTagsInMetadata:
type: boolean
includeExperimentScheduleInMetadata:
type: boolean
proxyEnabled:
type: boolean
proxyHost:
type: string
hashSecureAttributes:
type: boolean
remoteEvalEnabled:
type: boolean
savedGroupReferencesEnabled:
description: Deprecated. Use `savedGroupFormat`.
type: boolean
savedGroupFormat:
type: string
enum:
- inline
- referencesV1
- referencesV2
includeReferencedPrerequisites:
description: >-
Carry prerequisite Feature Flags into this payload even when
they target other Projects. Defaults to true for new
connections.
type: boolean
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
sdkConnection:
$ref: '#/components/schemas/SdkConnection'
required:
- sdkConnection
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT 'https://api.growthbook.io/api/v1/sdk-connections/{id}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteSdkConnection
summary: Deletes a single SDK connection
tags:
- sdk-connections
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/sdk-connections/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/sdk-connections/lookup/{key}:
get:
operationId: lookupSdkConnectionByKey
summary: Find a single sdk connection by its key
tags:
- sdk-connections
parameters:
- $ref: '#/components/parameters/key'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
sdkConnection:
$ref: '#/components/schemas/SdkConnection'
required:
- sdkConnection
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/sdk-connections/lookup/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/data-sources:
get:
operationId: listDataSources
summary: Get all data sources
tags:
- data-sources
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/projectId'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
dataSources:
type: array
items:
$ref: '#/components/schemas/DataSource'
required:
- dataSources
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/data-sources' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/data-sources/{id}:
get:
operationId: getDataSource
summary: Get a single data source
tags:
- data-sources
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
dataSource:
$ref: '#/components/schemas/DataSource'
required:
- dataSource
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/data-sources/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/data-sources/{dataSourceId}/information-schema:
get:
operationId: getInformationSchema
summary: Get a Data Source's Information Schema
description: >-
Returns cached database schema metadata for a data source, including
databases, schemas, and tables. The information schema is automatically
created when a SQL-based data source is added. Not all data source types
support information schemas.
tags:
- data-sources
parameters:
- $ref: '#/components/parameters/dataSourceId'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
informationSchema:
$ref: '#/components/schemas/InformationSchema'
required:
- informationSchema
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/data-sources/{dataSourceId}/information-schema'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/data-sources/{id}/sql/search-tables:
post:
operationId: searchWarehouseTables
summary: Search warehouse tables
tags:
- data-sources
parameters:
- name: id
in: path
required: true
description: The id of the data source
schema:
description: The id of the data source
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
query:
description: >-
Case-insensitive substring match on table name. Empty
returns all.
type: string
limit:
description: Max results to return. Defaults to 20.
type: integer
minimum: 1
maximum: 50
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
tables:
type: array
items:
$ref: '#/components/schemas/tables'
total:
type: number
schemas:
type: array
items:
type: string
datasourceType:
type: string
required:
- tables
- total
- schemas
- datasourceType
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/data-sources/{id}/sql/search-tables'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/data-sources/{id}/sql/table-schema:
post:
operationId: getWarehouseTableSchema
summary: Get warehouse table schemas
tags:
- data-sources
parameters:
- name: id
in: path
required: true
description: The id of the data source
schema:
description: The id of the data source
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
tables:
minItems: 1
maxItems: 5
type: array
items:
type: object
properties:
databaseName:
type: string
tableSchema:
type: string
tableName:
type: string
required:
- databaseName
- tableSchema
- tableName
additionalProperties: false
required:
- tables
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
tables:
type: array
items:
type: object
properties:
database:
type: string
schema:
type: string
table:
type: string
columns:
type: array
items:
type: object
properties:
name:
type: string
type:
type: string
description:
type: string
required:
- name
- type
additionalProperties: false
required:
- database
- schema
- table
- columns
additionalProperties: false
required:
- tables
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/data-sources/{id}/sql/table-schema'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/data-sources/{id}/sql/preview-values:
post:
operationId: previewWarehouseColumnValues
summary: Preview distinct column values
tags:
- data-sources
parameters:
- name: id
in: path
required: true
description: The id of the data source
schema:
description: The id of the data source
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
databaseName:
description: Database or project name.
type: string
tableSchema:
description: Schema or dataset name.
type: string
tableName:
description: Table name (unqualified).
type: string
columns:
minItems: 1
maxItems: 3
type: array
items:
type: string
limit:
description: Max rows to return. Defaults to 20.
type: integer
minimum: 1
maximum: 20
required:
- databaseName
- tableSchema
- tableName
- columns
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
anyOf:
- type: object
properties:
status:
type: string
const: success
table:
type: string
columns:
type: array
items:
type: string
rows:
type: array
items:
type: object
propertyNames:
type: string
additionalProperties: {}
rowCount:
type: number
warning:
type: string
required:
- status
- table
- columns
- rows
- rowCount
additionalProperties: false
- type: object
properties:
status:
type: string
const: error
message:
type: string
required:
- status
- message
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/data-sources/{id}/sql/preview-values'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/data-sources/{id}/sql/run-query:
post:
operationId: runSqlQuery
summary: Execute a read-only SQL query
tags:
- data-sources
parameters:
- name: id
in: path
required: true
description: The id of the data source
schema:
description: The id of the data source
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
sql:
description: A read-only SELECT or WITH query.
type: string
purpose:
description: One-line description of what this query answers.
type: string
confirm:
description: >-
Set to true to execute a query that previously returned
confirmation_required.
type: boolean
tableMetadata:
description: >-
Table metadata from earlier discovery steps. When provided,
the response includes an explorationUrl for viewing results
in the product analytics explorer.
type: object
properties:
table:
description: Table name, e.g. 'events'
type: string
path:
description: Fully qualified path, e.g. 'db.schema.events'
type: string
timestampColumn:
description: A date/timestamp column name
type: string
columnTypes:
description: Map of column names to types
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- string
- number
- date
- boolean
- other
required:
- table
- path
- timestampColumn
- columnTypes
additionalProperties: false
required:
- sql
- purpose
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
anyOf:
- type: object
properties:
status:
type: string
const: success
summary:
type: string
rowCount:
type: number
columns:
type: array
items:
type: object
properties:
name:
type: string
dataType:
type: string
required:
- name
additionalProperties: false
resultCsv:
type: string
truncated:
type: boolean
durationMs:
type: number
sql:
type: string
explorationUrl:
type: string
explorationId:
type: string
notice:
type: string
required:
- status
- summary
- rowCount
- columns
- resultCsv
- truncated
- durationMs
- sql
additionalProperties: false
- type: object
properties:
status:
type: string
const: confirmation_required
estimatedBytesProcessed:
type: number
estimatedCostUsd:
type: number
sql:
type: string
message:
type: string
required:
- status
- estimatedBytesProcessed
- sql
- message
additionalProperties: false
- type: object
properties:
status:
type: string
const: error
message:
type: string
required:
- status
- message
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/data-sources/{id}/sql/run-query' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/visual-changesets/{id}:
get:
operationId: getVisualChangeset
summary: Get a single visual changeset
tags:
- visual-changesets
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/includeExperiment'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
visualChangeset:
$ref: '#/components/schemas/VisualChangeset'
experiment:
anyOf:
- title: Experiment
$ref: '#/components/schemas/Experiment'
- title: Visual Editor Cb Experiment Stub
$ref: '#/components/schemas/VisualEditorCbExperimentStub'
required:
- visualChangeset
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/visual-changesets/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: putVisualChangeset
summary: Update a visual changeset
tags:
- visual-changesets
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
editorUrl:
description: >-
URL of the page opened in the visual editor when creating
this changeset
type: string
urlPatterns:
description: >-
URL patterns that determine which pages this visual
changeset applies to
type: array
items:
type: object
properties:
include:
type: boolean
type:
type: string
enum:
- simple
- regex
pattern:
type: string
required:
- type
- pattern
additionalProperties: {}
allowRunningExperiment:
description: >-
Also accept the write when the experiment is running. Off by
default so a stale editor can't change a live test. When
set, the change reaches live traffic immediately and the
caller needs the runExperiments permission on the affected
environments; the write is audited.
type: boolean
visualChanges:
type: array
items:
type: object
properties:
id:
type: string
description:
type: string
css:
type: string
js:
type: string
variation:
type: string
domMutations:
type: array
items:
type: object
properties:
selector:
type: string
action:
type: string
enum:
- append
- set
- remove
attribute:
type: string
value:
type: string
parentSelector:
type: string
insertBeforeSelector:
type: string
required:
- selector
- action
- attribute
additionalProperties: {}
required:
- variation
additionalProperties: {}
additionalProperties: {}
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
nModified:
type: number
visualChangeset:
$ref: '#/components/schemas/VisualChangeset'
required:
- nModified
- visualChangeset
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/visual-changesets/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"editorUrl":"https://example.com/"}'
/v1/visual-changesets/{id}/visual-change:
post:
operationId: postVisualChange
summary: Create a visual change for a visual changeset
tags:
- visual-changesets
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
type: string
description:
type: string
css:
type: string
js:
type: string
variation:
type: string
allowRunningExperiment:
description: >-
Also accept the write when the experiment is running. Off by
default so a stale editor can't change a live test. When
set, the change reaches live traffic immediately and the
caller needs the runExperiments permission on the affected
environments; the write is audited.
type: boolean
domMutations:
type: array
items:
type: object
properties:
selector:
type: string
action:
type: string
enum:
- append
- set
- remove
attribute:
type: string
value:
type: string
parentSelector:
type: string
insertBeforeSelector:
type: string
required:
- selector
- action
- attribute
additionalProperties: {}
required:
- variation
additionalProperties: {}
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
nModified:
type: number
visualChangeId:
type: string
required:
- nModified
- visualChangeId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/visual-changesets/abc123/visual-change'
\
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"variation":"var_abc123","domMutations":[]}'
/v1/visual-changesets/{id}/visual-change/{visualChangeId}:
put:
operationId: putVisualChange
summary: Update a visual change for a visual changeset
tags:
- visual-changesets
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/visualChangeId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
description:
type: string
css:
type: string
js:
type: string
variation:
type: string
allowRunningExperiment:
description: >-
Also accept the write when the experiment is running. Off by
default so a stale editor can't change a live test. When
set, the change reaches live traffic immediately and the
caller needs the runExperiments permission on the affected
environments; the write is audited.
type: boolean
domMutations:
type: array
items:
type: object
properties:
selector:
type: string
action:
type: string
enum:
- append
- set
- remove
attribute:
type: string
value:
type: string
parentSelector:
type: string
insertBeforeSelector:
type: string
required:
- selector
- action
- attribute
additionalProperties: {}
additionalProperties: {}
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
nModified:
type: number
required:
- nModified
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/visual-changesets/abc123/visual-change/vc_abc123'
\
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"css":"h1 { color: red; }"}'
/v1/saved-groups:
get:
operationId: listSavedGroups
summary: Get all saved group
tags:
- saved-groups
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- name: type
in: query
description: Only list Saved Groups of this type
schema:
description: Only list Saved Groups of this type
type: string
enum:
- condition
- list
- remote
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
savedGroups:
type: array
items:
$ref: '#/components/schemas/SavedGroup'
required:
- savedGroups
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/saved-groups' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postSavedGroup
summary: Create a single saved group
tags:
- saved-groups
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: >-
Short display name (e.g. `Internal employees`). Put details
in `description`.
type: string
description:
description: >-
Short note (max 100 characters) on who is in the Saved Group
and why.
type: string
maxLength: 100
type:
description: >-
The type of Saved Group (inferred from other arguments if
missing)
type: string
enum:
- condition
- list
- remote
condition:
description: >-
When type = 'condition', this is the JSON-encoded condition
for the group
type: string
attributeKey:
description: >-
When type = 'list' or 'remote', this is the attribute key
the group is based on
type: string
values:
description: >-
When type = 'list', this is the list of values for the
attribute key
type: array
items:
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. When
omitted, it defaults to the requesting member: a personal
access token's owner, or the member an organization API key
assumes. An organization API key acting as itself leaves it
empty.
type: string
projects:
type: array
items:
type: string
bypassApproval:
description: >-
Set to true to create the live Saved Group without approval.
The caller must have Bypass draft approvals access in every
assigned Project. This field has no effect when approval is
not required.
type: boolean
required:
- name
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
savedGroup:
$ref: '#/components/schemas/SavedGroup'
required:
- savedGroup
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/saved-groups' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"name":"Internal users","values":["userId-123","userId-345","userId-678"],"attributeKey":"userId","owner":""}'
/v1/saved-groups-revisions:
get:
operationId: listSavedGroupRevisions
summary: List saved-group revisions across the organization
description: >-
Returns a paginated list of revisions across all saved groups in the
organization, sorted newest-first. Optionally filtered by saved group,
status, author, or the calling user's involvement.
tags:
- saved-group-revisions
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/skipPagination'
- $ref: '#/components/parameters/savedGroupId'
- name: status
in: query
description: >-
Filter by revision status. Accepts a comma-separated list, or the
literal `open` for non-merged/non-discarded revisions.
schema:
description: >-
Filter by revision status. Accepts a comma-separated list, or the
literal `open` for non-merged/non-discarded revisions.
type: string
- $ref: '#/components/parameters/author'
- name: mine
in: query
description: >-
If true, return only revisions authored by the calling user. Needs a
personal access token, or an organization API key that assumes a
named member's role. Mutually exclusive with `author`.
schema:
description: >-
If true, return only revisions authored by the calling user. Needs
a personal access token, or an organization API key that assumes a
named member's role. Mutually exclusive with `author`.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revisions:
type: array
items:
$ref: '#/components/schemas/SavedGroupRevision'
limit:
type: integer
offset:
type: integer
count:
type: integer
total:
type: integer
hasMore:
type: boolean
nextOffset:
anyOf:
- type: integer
- type: 'null'
required:
- revisions
- limit
- offset
- count
- total
- hasMore
- nextOffset
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/saved-groups-revisions' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups/{id}:
get:
operationId: getSavedGroup
summary: Get a single saved group
tags:
- saved-groups
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
savedGroup:
$ref: '#/components/schemas/SavedGroup'
required:
- savedGroup
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/saved-groups/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: updateSavedGroup
summary: Partially update a single saved group
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.
tags:
- saved-groups
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: >-
Short display name (e.g. `Internal employees`). Put details
in `description`.
type: string
description:
description: >-
Short note (max 100 characters) on who is in the Saved Group
and why.
type: string
condition:
description: >-
When type = 'condition', this is the JSON-encoded condition
for the group
type: string
values:
description: >-
When type = 'list', this is the list of values for the
attribute key
type: array
items:
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
projects:
type: array
items:
type: string
currentUploadVersion:
description: >-
When type = 'remote', the upload whose IDs the group uses.
Must be a valid upload of this group.
type: integer
exclusiveMinimum: 0
bypassApproval:
description: >-
Set to true to update the live Saved Group without approval.
The caller must have Bypass draft approvals access in every
current and destination Project. This field has no effect
when approval is not required.
type: boolean
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
savedGroup:
$ref: '#/components/schemas/SavedGroup'
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:
- savedGroup
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST 'https://api.growthbook.io/api/v1/saved-groups/abc123'
\
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"values":["userId-123","userId-345"]}'
delete:
operationId: deleteSavedGroup
summary: Deletes a single saved group
tags:
- saved-groups
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/saved-groups/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups/{id}/archive:
post:
operationId: archiveSavedGroup
summary: Archive a single saved group
description: >-
Archives a Saved Group. If it is still referenced by a Feature Flag,
experiment, or another Saved Group, the API returns 422 with the
affected references. Send `"ignoreWarnings": true` to acknowledge those
references and continue. When approval is required, create and publish
an archive revision instead, or use a caller with Bypass draft approvals
access. A successful response lists any skipped gates in
`bypassedGates`.
tags:
- saved-groups
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
savedGroup:
$ref: '#/components/schemas/SavedGroup'
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:
- savedGroup
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/saved-groups/abc123/archive' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups/{id}/unarchive:
post:
operationId: unarchiveSavedGroup
summary: Unarchive a single saved group
description: >-
Unarchives a Saved Group. When approval is required, create and publish
an unarchive revision instead, or use a caller with Bypass draft
approvals access. A successful response lists any skipped gates in
`bypassedGates`.
tags:
- saved-groups
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
savedGroup:
$ref: '#/components/schemas/SavedGroup'
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:
- savedGroup
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/saved-groups/abc123/unarchive' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups/{id}/references:
get:
operationId: getSavedGroupReferences
summary: >-
Get features, experiments, and saved groups that reference this saved
group
tags:
- saved-groups
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Successful response
content:
application/json:
schema:
id: SavedGroupReferences
type: object
properties:
features:
type: array
items:
$ref: '#/components/schemas/SavedGroupReferenceResource'
experiments:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
project:
type: string
projects:
type: array
items:
type: string
required:
- id
additionalProperties: false
contextualBandits:
type: array
items:
$ref: '#/components/schemas/SavedGroupReferenceResource'
interleavings:
type: array
items:
$ref: '#/components/schemas/SavedGroupReferenceResource'
savedGroups:
type: array
items:
$ref: '#/components/schemas/savedGroups'
required:
- features
- experiments
- contextualBandits
- interleavings
- savedGroups
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/saved-groups/abc123/references' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups/{id}/uploads:
get:
operationId: listSavedGroupUploads
summary: List the uploads of a remote saved group
description: Newest first.
tags:
- saved-groups
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
uploads:
type: array
items:
$ref: '#/components/schemas/SavedGroupUpload'
limit:
type: integer
offset:
type: integer
count:
type: integer
total:
type: integer
hasMore:
type: boolean
nextOffset:
anyOf:
- type: integer
- type: 'null'
required:
- uploads
- limit
- offset
- count
- total
- hasMore
- nextOffset
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/saved-groups/abc123/uploads' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postSavedGroupUpload
summary: Upload a new version of a remote saved group's IDs
description: >-
Records the next version of the group's IDs. The start and end of the
file are checked for one ID per line, then the whole file in the
background; loaders trim and deduplicate the IDs. Poll `GET
/saved-groups/{id}/uploads/{version}` until it's valid, then set the
group's `currentUploadVersion` with `PUT
/saved-groups-revisions/{id}/{version}/upload-version` to use it.
Loaders pick up the group's version from `currentUpload` and download it
from `GET /saved-groups/{id}/uploads/{version}/file`, which redirects to
a short-lived signed storage URL.
tags:
- saved-groups
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
fileKey:
description: The `fileKey` from the upload URL endpoint
type: string
fileName:
description: The file's original name, used when downloading it
type: string
minLength: 1
maxLength: 255
required:
- fileKey
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
upload:
$ref: '#/components/schemas/SavedGroupUpload'
required:
- upload
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/saved-groups/abc123/uploads' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"fileKey":"org_abc/remote-saved-groups/grp_123/staging/1234.csv"}'
/v1/saved-groups/{id}/upload-url:
post:
operationId: postSavedGroupUploadUrl
summary: Get a signed URL to upload a remote saved group CSV
description: >-
Upload a CSV with one ID per line to the returned URL with
`Content-Type: text/csv`, then create an upload with the `fileKey`. A
first line equal to the attribute name is a header. Needs S3 or Google
Cloud Storage.
tags:
- saved-groups
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
signedUrl:
type: string
fields:
description: >-
Form fields for an S3 presigned POST. When null, PUT the
file to `signedUrl` instead.
anyOf:
- type: object
propertyNames:
type: string
additionalProperties:
type: string
- type: 'null'
fileKey:
description: Pass this to the create upload endpoint after uploading
type: string
maxBytes:
type: integer
expiresAt:
format: date-time
type: string
required:
- signedUrl
- fields
- fileKey
- maxBytes
- expiresAt
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/saved-groups/abc123/upload-url' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups/{id}/uploads/{version}/loads:
post:
operationId: postSavedGroupUploadLoad
summary: Report loading a remote saved group upload into a data store
description: >-
Called by remote saved group loaders. Each report replaces the previous
one from the same `storeId`. Needs permission to publish the saved
group.
tags:
- saved-groups
parameters:
- name: id
in: path
required: true
description: The id of the remote saved group
schema:
description: The id of the remote saved group
type: string
- name: version
in: path
required: true
description: ''
schema:
type: integer
exclusiveMinimum: 0
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
storeId:
description: >-
The data store's ID, such as `redis-us-east`, set in the
loader's config. Loaders sharing a store (such as one Redis)
use the same ID. Shown in the UI.
type: string
minLength: 1
maxLength: 100
status:
description: >-
Loaders validate the file while loading it, so each store
reports its own result.
anyOf:
- type: object
properties:
type:
type: string
const: loading
required:
- type
additionalProperties: false
- type: object
properties:
type:
type: string
const: loaded
rowCount:
description: Unique IDs loaded
type: integer
minimum: 0
required:
- type
- rowCount
additionalProperties: false
- description: >-
The file has problems, so the store kept serving the
previous upload
type: object
properties:
type:
type: string
const: invalid
invalidLineCount:
type: integer
minimum: 0
errors:
description: The first problems found in the file
maxItems: 10
type: array
items:
type: string
maxLength: 500
required:
- type
- invalidLineCount
- errors
additionalProperties: false
- type: object
properties:
type:
type: string
const: failed
error:
description: A problem in the data store, not the file
type: string
maxLength: 2000
required:
- type
- error
additionalProperties: false
required:
- storeId
- status
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
upload:
$ref: '#/components/schemas/SavedGroupUpload'
required:
- upload
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/saved-groups/abc123/uploads/3/loads'
\
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"storeId":"redis-us-east","status":{"type":"loaded","rowCount":120000}}'
/v1/saved-groups/{id}/uploads/{version}:
get:
operationId: getSavedGroupUpload
summary: Get one upload of a remote saved group
description: >-
Returns an upload of any status. After creating an upload, poll this
until `status.type` is `valid` or `invalid`.
tags:
- saved-groups
parameters:
- name: id
in: path
required: true
description: The id of the remote saved group
schema:
description: The id of the remote saved group
type: string
- name: version
in: path
required: true
description: ''
schema:
type: integer
exclusiveMinimum: 0
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
upload:
$ref: '#/components/schemas/SavedGroupUpload'
required:
- upload
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/saved-groups/abc123/uploads/3' \
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteSavedGroupUpload
summary: Delete an upload of a remote saved group
description: >-
Deletes the upload and its file. The version the group uses, or one an
open draft uses, can't be deleted. Version numbers aren't reused. Needs
permission to publish the saved group.
tags:
- saved-groups
parameters:
- name: id
in: path
required: true
description: The id of the remote saved group
schema:
description: The id of the remote saved group
type: string
- name: version
in: path
required: true
description: ''
schema:
type: integer
exclusiveMinimum: 0
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedVersion:
type: integer
required:
- deletedVersion
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/saved-groups/abc123/uploads/3' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}:
get:
operationId: getSavedGroupRevisions
summary: List revisions for a saved group
description: >-
Returns a paginated list of revisions for this saved group, sorted
newest-first. Optionally filtered by status, author, or the calling
user's involvement.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/skipPagination'
- name: status
in: query
description: >-
Filter by revision status. Accepts a comma-separated list, or the
literal `open` for non-merged/non-discarded revisions.
schema:
description: >-
Filter by revision status. Accepts a comma-separated list, or the
literal `open` for non-merged/non-discarded revisions.
type: string
- $ref: '#/components/parameters/author'
- name: mine
in: query
description: >-
If true, return only revisions authored by the calling user. Needs a
personal access token, or an organization API key that assumes a
named member's role. Mutually exclusive with `author`.
schema:
description: >-
If true, return only revisions authored by the calling user. Needs
a personal access token, or an organization API key that assumes a
named member's role. Mutually exclusive with `author`.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revisions:
type: array
items:
$ref: '#/components/schemas/SavedGroupRevision'
limit:
type: integer
offset:
type: integer
count:
type: integer
total:
type: integer
hasMore:
type: boolean
nextOffset:
anyOf:
- type: integer
- type: 'null'
required:
- revisions
- limit
- offset
- count
- total
- hasMore
- nextOffset
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/saved-groups-revisions/grp_abc123'
\
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postSavedGroupRevision
summary: Create a draft revision
description: >-
Creates a new draft revision branched from the current live saved group.
A saved group can have multiple concurrent drafts; use this to start an
isolated line of edits.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
description: Short draft title (e.g. `Enable for beta testers`).
type: string
comment:
description: Markdown. What changed and why, for reviewers.
type: string
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/SavedGroupRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/latest:
get:
operationId: getSavedGroupRevisionLatest
summary: Get the most recent active draft revision
description: >-
Returns the most recently updated open (non-merged, non-discarded)
revision for the saved group. Returns 404 if there is no active draft.
Pass `mine=true` to restrict to drafts authored by the calling user.
Needs a personal access token, or an organization API key that assumes a
named member's role.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
in: path
required: true
description: ''
schema:
type: string
- name: mine
in: query
description: >-
If true, return only the most recent active draft authored by the
calling user. Needs a personal access token, or an organization API
key that assumes a named member's role.
schema:
description: >-
If true, return only the most recent active draft authored by the
calling user. Needs a personal access token, or an organization
API key that assumes a named member's role.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/SavedGroupRevision'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/saved-groups-revisions/grp_abc123/latest'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/{version}:
get:
operationId: getSavedGroupRevision
summary: Get a single saved group revision
description: >-
Returns the revision at the specified version for this saved group. Use
`GET /saved-groups-revisions/{savedGroupId}/latest` for the most recent
active draft.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/SavedGroupRevision'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/saved-groups-revisions/grp_abc123/3'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/{version}/metadata:
put:
operationId: putSavedGroupRevisionMetadata
summary: Update saved group metadata in a draft revision
description: >-
Stages metadata changes (name, owner, description, projects) on the
draft. Pass `version: "new"` to auto-create a draft. The change is only
applied to the live saved group when the revision is merged.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
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:
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
name:
description: >-
Short display name (e.g. `Internal employees`). Put details
in `description`.
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
description:
description: >-
Short note (max 100 characters) on who is in the Saved Group
and why.
type: string
projects:
type: array
items:
type: string
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/SavedGroupRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}/{version}/metadata'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/{version}/condition:
put:
operationId: putSavedGroupRevisionCondition
summary: Update the condition of a condition saved group draft revision
description: >-
Stages a new JSON-encoded condition for the draft. Only valid for
`condition` saved groups. Pass `version: "new"` to auto-create a draft.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
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:
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
condition:
description: The JSON-encoded condition for the saved group
type: string
required:
- condition
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/SavedGroupRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}/{version}/condition'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/{version}/values:
put:
operationId: putSavedGroupRevisionValues
summary: Replace the values list in a list saved group draft revision
description: >-
Replaces the entire `values` array atomically. Only valid for `list`
saved groups. For safe concurrent updates against a draft, prefer `POST
.../items/add` and `POST .../items/remove`. Pass `version: "new"` to
auto-create a draft.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
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:
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
values:
type: array
items:
type: string
required:
- values
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/SavedGroupRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}/{version}/values'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/{version}/upload-version:
put:
operationId: putSavedGroupRevisionUploadVersion
summary: Set the upload a remote saved group draft revision uses
description: >-
Stages which upload the group uses. Only valid for `remote` saved
groups, and the upload must be valid. Pass `version: "new"` to
auto-create a draft.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
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:
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
currentUploadVersion:
description: The version of the upload the group uses
type: integer
exclusiveMinimum: 0
required:
- currentUploadVersion
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/SavedGroupRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}/{version}/upload-version'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/{version}/archive:
put:
operationId: putSavedGroupRevisionArchive
summary: Stage an archive/unarchive in a draft revision
description: >-
Stages an archive or unarchive on the draft. Pass `version: "new"` to
auto-create a draft. Archived saved groups can be permanently deleted
via `DELETE /saved-groups/{id}` once the archive is published.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
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:
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
archived:
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. 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/SavedGroupRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}/{version}/archive'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/{version}/items/add:
post:
operationId: postSavedGroupRevisionItemsAdd
summary: Append items to a list saved group draft revision
description: >-
Appends the provided items (deduplicated) to the draft's `values` array.
Only valid for `list` saved groups. Pass `version: "new"` to auto-create
a draft. Duplicate items are merged on top of any existing draft, so
multiple successive add/remove calls accumulate.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
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:
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
items:
type: array
items:
type: string
required:
- items
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/SavedGroupRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}/{version}/items/add'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/{version}/items/remove:
post:
operationId: postSavedGroupRevisionItemsRemove
summary: Remove items from a list saved group draft revision
description: >-
Removes the provided items from the draft's `values` array. Only valid
for `list` saved groups. Pass `version: "new"` to auto-create a draft.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
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:
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
items:
type: array
items:
type: string
required:
- items
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/SavedGroupRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}/{version}/items/remove'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/{version}/request-review:
post:
operationId: postSavedGroupRevisionRequestReview
summary: Request review for a draft revision
description: >-
Moves the draft from `draft` into `pending-review`. Notifies reviewers
per the org's approval-flow settings.
Set `autoPublishOnApproval` to `true` to publish the revision
automatically the moment it is approved (GitHub auto-merge model). This
requires the org to have auto-publish-on-approval enabled and the caller
to have publish permission on the saved group; the auto-publish then
executes with the caller's authority.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
autoPublishOnApproval:
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. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/SavedGroupRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}/{version}/request-review'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/{version}/submit-review:
post:
operationId: postSavedGroupRevisionSubmitReview
summary: Submit a review on a draft revision
description: >-
Submits an `approve`, `request-changes`, or `comment` review on the
revision. The verdict belongs to whoever the request acts as; see
[Naming who asked](/api/introduction#naming-who-asked). No one can rule
on a draft they created. Submitting `approve` or `request-changes` needs
Review access. A `comment` is participation rather than a verdict, so it
is also open to the Comments permission or draft authority on the
entity. Authors and contributors cannot submit `approve` reviews on
their own drafts when the org has `blockSelfApproval` enabled.
When `decision` is `approve` and the revision has
`autoPublishOnApproval` enabled, the revision is automatically published
after approval. The response includes `autoPublished: true` when this
happens. Pass `skipAutoPublish: true` to approve without triggering
auto-publish.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
decision:
type: string
enum:
- approve
- request-changes
- comment
comment:
description: Markdown. Why you approved, requested changes or commented.
type: string
skipAutoPublish:
type: boolean
required:
- decision
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/SavedGroupRevision'
autoPublished:
type: boolean
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}/{version}/submit-review'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/{version}/recall-review:
post:
operationId: postSavedGroupRevisionRecallReview
summary: Recall a review request
description: >-
Pulls a revision in review (`pending-review`, `changes-requested`, or
`approved`) back to `draft`, clearing existing reviews and disarming any
auto-publish-on-approval.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/SavedGroupRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}/{version}/recall-review'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/{version}/reopen:
post:
operationId: postSavedGroupRevisionReopen
summary: Reopen a discarded revision
description: >-
Returns a previously discarded revision to `draft` status so it can be
edited and published again. Only discarded revisions can be reopened.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/SavedGroupRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}/{version}/reopen'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/{version}/schedule-publish:
post:
operationId: postSavedGroupRevisionSchedulePublish
summary: Schedule (or cancel) a deferred publish
description: >-
Arms a revision to publish automatically at a future time. Pass
`scheduledPublishAt` as an RFC3339 timestamp in the future to arm, or
`null` to cancel a pending schedule. Requires the `scheduled-revisions`
commercial feature and publish permission on the Saved Group. A draft
that still requires approval must request review first (or be armed with
`bypassApproval` by a caller who can bypass).
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
scheduledPublishAt:
description: >-
When to publish, as an RFC3339 timestamp (e.g.
`2026-01-31T09:00:00Z` or `2026-01-31T02:00:00-07:00`), or
`null` to cancel a pending schedule.
anyOf:
- type: string
format: date-time
- type: 'null'
lockEdits:
type: boolean
lockOthers:
type: boolean
bypassApproval:
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. 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:
- scheduledPublishAt
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/SavedGroupRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}/{version}/schedule-publish'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/{version}/undo-review:
post:
operationId: postSavedGroupRevisionUndoReview
summary: Retract your own review verdict
description: >-
Retracts the calling user's own active `approve` or `request-changes`
verdict, returning the revision to `pending-review`. Review comments
stay in the log. Retracting a `request-changes` can leave the revision
approved by someone else, in which case an armed auto-publish fires. The
verdict belongs to whoever the request acts as; see [Naming who
asked](/api/introduction#naming-who-asked). No one can rule on a draft
they created.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/SavedGroupRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}/{version}/undo-review'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/{version}/merge-status:
get:
operationId: getSavedGroupRevisionMergeStatus
summary: Get merge status for a draft revision
description: >-
Runs a dry-run merge of the draft against the current live saved group
and returns any conflicts. Use this before publishing to preview changes
and detect conflicting edits.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
hasConflicts:
type: boolean
conflicts:
type: array
items:
type: object
properties:
field:
type: string
baseValue: {}
liveValue: {}
proposedValue: {}
required:
- field
- baseValue
- liveValue
- proposedValue
additionalProperties: false
canAutoMerge:
type: boolean
required:
- success
- hasConflicts
- conflicts
- canAutoMerge
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}/{version}/merge-status'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/{version}/rebase:
post:
operationId: postSavedGroupRevisionRebase
summary: Rebase a draft revision onto the current live saved group
description: >-
Updates the draft's base snapshot to the current live state, applying
the draft's changes on top. Supply `conflictResolutions` to resolve any
conflicting fields. Strategies are `overwrite` (use the draft's value),
`discard` (keep the live value), or `union` (merge arrays — use only on
`values`). Optimistic locking is not enforced by this endpoint; callers
who need strict locking should call `merge-status` before and after.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
conflictResolutions:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- overwrite
- discard
- union
customValues:
description: >-
Custom values to use for `union` strategy fields. Keyed by
field name.
type: object
propertyNames:
type: string
additionalProperties:
type: array
items: {}
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/SavedGroupRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}/{version}/rebase'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/{version}/publish:
post:
operationId: postSavedGroupRevisionPublish
summary: Publish a draft revision
description: >-
Publishes the draft and applies its changes to the live Saved Group. The
caller needs Publish access in every assigned Project. When approval is
required, the draft must be approved unless the caller has Bypass draft
approvals access. If the organization requires rebasing, an out-of-date
draft must be rebased first; an authorized caller can instead send
`ignoreWarnings: true` to force-publish it. A 422 response lists every
blocking gate and the available resolution.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
bypassApproval:
description: >-
Deprecated and ignored. Approval is bypassed automatically
when the caller has Bypass draft approvals access for this
resource or when the organization enables the REST API
approval bypass. Otherwise, the revision must be approved
before it can be published.
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. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/SavedGroupRevision'
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:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}/{version}/publish'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/{version}/discard:
post:
operationId: postSavedGroupRevisionDiscard
summary: Discard a draft revision
description: >-
Permanently discards a draft revision. Only open revisions (not merged
or already-discarded) can be discarded.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
reason:
type: string
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/SavedGroupRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}/{version}/discard'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/saved-groups-revisions/{savedGroupId}/{version}/revert:
post:
operationId: postSavedGroupRevisionRevert
summary: Revert the saved group to a prior revision
description: >-
Creates a new draft (or immediately publishes) whose content matches the
specified historical revision. Defaults to creating a draft; when the
org enables 'reverts bypass approval' it defaults to publishing
immediately. Pass `strategy` to override.
tags:
- saved-group-revisions
parameters:
- name: savedGroupId
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
strategy:
description: >-
Whether to stage the revert as a draft or publish it
immediately. Defaults to `draft`, or to `publish` when the
org enables 'reverts bypass approval'.
type: string
enum:
- draft
- publish
title:
description: Short draft title (e.g. `Enable for beta testers`).
type: string
comment:
description: Currently ignored. Use `title` to describe the revert.
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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/SavedGroupRevision'
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:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}/{version}/revert'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants:
get:
operationId: listConstants
summary: Get all constants
tags:
- constants
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
constants:
type: array
items:
$ref: '#/components/schemas/Constant'
required:
- constants
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/constants' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postConstant
summary: Create a single constant
tags:
- constants
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
key:
description: >-
Stable reference handle (lowercase slug, unique per org),
referenced as `@const:key`
type: string
pattern: ^[a-z0-9][a-z0-9\-_]*$
name:
description: The display name of the constant
type: string
type:
description: >-
`string` (interpolated as `{{ @const:key }}`) or `json`
(substituted as a whole value)
type: string
enum:
- string
- json
value:
type: string
environmentValues:
type: object
propertyNames:
type: string
additionalProperties:
type: string
description:
description: Markdown. Put context here, not in the name.
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. When
omitted, it defaults to the requesting member: a personal
access token's owner, or the member an organization API key
assumes. An organization API key acting as itself leaves it
empty.
type: string
required:
- key
- name
- type
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
constant:
$ref: '#/components/schemas/Constant'
required:
- constant
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/constants' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"key":"config-snippet","name":"Config Snippet","type":"json","value":"{\"timeout\":30}"}'
/v1/constants-revisions:
get:
operationId: listConstantRevisions
summary: List constant revisions across the organization
description: >-
Returns a paginated list of revisions across all constants in the
organization, sorted newest-first. Optionally filtered by constant,
status, author, or the calling user's involvement.
tags:
- constant-revisions
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/skipPagination'
- name: key
in: query
description: >-
Restrict results to revisions for a single constant (by its key).
When omitted, returns revisions across every constant the caller can
read.
schema:
description: >-
Restrict results to revisions for a single constant (by its key).
When omitted, returns revisions across every constant the caller
can read.
type: string
- name: status
in: query
description: >-
Filter by revision status. Accepts a comma-separated list, or the
literal `open` for non-merged/non-discarded revisions.
schema:
description: >-
Filter by revision status. Accepts a comma-separated list, or the
literal `open` for non-merged/non-discarded revisions.
type: string
- $ref: '#/components/parameters/author'
- name: mine
in: query
description: >-
If true, return only revisions authored by the calling user. Needs a
personal access token, or an organization API key that assumes a
named member's role. Mutually exclusive with `author`.
schema:
description: >-
If true, return only revisions authored by the calling user. Needs
a personal access token, or an organization API key that assumes a
named member's role. Mutually exclusive with `author`.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revisions:
type: array
items:
$ref: '#/components/schemas/ConstantRevision'
limit:
type: integer
offset:
type: integer
count:
type: integer
total:
type: integer
hasMore:
type: boolean
nextOffset:
anyOf:
- type: integer
- type: 'null'
required:
- revisions
- limit
- offset
- count
- total
- hasMore
- nextOffset
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/constants-revisions' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants/{key}/references:
get:
operationId: getConstantReferences
summary: Get features and constants that reference this constant
tags:
- constants
parameters:
- name: key
in: path
required: true
description: The key of the constant
schema:
description: The key of the constant
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
id: ConstantReferences
type: object
properties:
features:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
project:
type: string
required:
- id
additionalProperties: false
constants:
type: array
items:
$ref: '#/components/schemas/constants'
required:
- features
- constants
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/constants/config-snippet/references'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants/{key}:
get:
operationId: getConstant
summary: Get a single constant
tags:
- constants
parameters:
- name: key
in: path
required: true
description: The key of the constant
schema:
description: The key of the constant
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
constant:
$ref: '#/components/schemas/Constant'
required:
- constant
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/constants/config-snippet' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: updateConstant
summary: Partially update a single constant
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.
tags:
- constants
parameters:
- name: key
in: path
required: true
description: The key of the constant
schema:
description: The key of the constant
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name. Put details in `description`.
type: string
value:
type: string
environmentValues:
description: >-
Per-environment value overrides (environment id → value).
When provided, this REPLACES the entire override map — send
the complete set, not just the environments you want to
change (omit the field to leave overrides unchanged).
type: object
propertyNames:
type: string
additionalProperties:
type: string
description:
description: Markdown. Put context here, not in the name.
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
bypassApproval:
description: >-
Set to true to write directly to the live Constant without
approval. The caller must have Bypass draft approvals access
in the Constant'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. 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
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. 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
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. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
constant:
$ref: '#/components/schemas/Constant'
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:
- constant
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/constants/config-snippet' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"value":"{\"timeout\":60}"}'
delete:
operationId: deleteConstant
summary: Delete a single constant
tags:
- constants
parameters:
- name: key
in: path
required: true
description: The key of the constant
schema:
description: The key of the constant
type: string
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/constants/config-snippet' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants/{key}/archive:
post:
operationId: archiveConstant
summary: Archive a single constant
tags:
- constants
parameters:
- name: key
in: path
required: true
description: The key of the constant
schema:
description: The key of the constant
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
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
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. 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
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. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
constant:
$ref: '#/components/schemas/Constant'
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:
- constant
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/constants/config-snippet/archive'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants/{key}/unarchive:
post:
operationId: unarchiveConstant
summary: Unarchive a single constant
tags:
- constants
parameters:
- name: key
in: path
required: true
description: The key of the constant
schema:
description: The key of the constant
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
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
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. 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
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. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
constant:
$ref: '#/components/schemas/Constant'
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:
- constant
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/constants/config-snippet/unarchive'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants-revisions/{key}:
get:
operationId: getConstantRevisions
summary: List revisions for a constant
description: >-
Returns a paginated list of revisions for this constant, sorted
newest-first. Optionally filtered by status, author, or the calling
user's involvement.
tags:
- constant-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/skipPagination'
- name: status
in: query
description: >-
Filter by revision status. Accepts a comma-separated list, or the
literal `open` for non-merged/non-discarded revisions.
schema:
description: >-
Filter by revision status. Accepts a comma-separated list, or the
literal `open` for non-merged/non-discarded revisions.
type: string
- $ref: '#/components/parameters/author'
- name: mine
in: query
description: >-
If true, return only revisions authored by the calling user. Needs a
personal access token, or an organization API key that assumes a
named member's role. Mutually exclusive with `author`.
schema:
description: >-
If true, return only revisions authored by the calling user. Needs
a personal access token, or an organization API key that assumes a
named member's role. Mutually exclusive with `author`.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revisions:
type: array
items:
$ref: '#/components/schemas/ConstantRevision'
limit:
type: integer
offset:
type: integer
count:
type: integer
total:
type: integer
hasMore:
type: boolean
nextOffset:
anyOf:
- type: integer
- type: 'null'
required:
- revisions
- limit
- offset
- count
- total
- hasMore
- nextOffset
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/constants-revisions/config-snippet'
\
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postConstantRevision
summary: Create a draft revision
description: >-
Creates a new draft revision branched from the current live constant. A
constant can have multiple concurrent drafts; use this to start an
isolated line of edits.
tags:
- constant-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
type: string
comment:
type: string
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConstantRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/constants-revisions/{key}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants-revisions/{key}/latest:
get:
operationId: getConstantRevisionLatest
summary: Get the most recent active draft revision
description: >-
Returns the most recently updated open (non-merged, non-discarded)
revision for the constant. Returns 404 if there is no active draft. Pass
`mine=true` to restrict to drafts authored by the calling user. Needs a
personal access token, or an organization API key that assumes a named
member's role.
tags:
- constant-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- name: mine
in: query
description: >-
If true, return only the most recent active draft authored by the
calling user. Needs a personal access token, or an organization API
key that assumes a named member's role.
schema:
description: >-
If true, return only the most recent active draft authored by the
calling user. Needs a personal access token, or an organization
API key that assumes a named member's role.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConstantRevision'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/constants-revisions/config-snippet/latest'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants-revisions/{key}/{version}:
get:
operationId: getConstantRevision
summary: Get a single constant revision
description: >-
Returns the revision at the specified version for this constant. Use
`GET /constants-revisions/{key}/latest` for the most recent active
draft.
tags:
- constant-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConstantRevision'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/constants-revisions/config-snippet/3'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants-revisions/{key}/{version}/metadata:
put:
operationId: putConstantRevisionMetadata
summary: Update constant metadata in a draft revision
description: >-
Stages metadata changes (name, owner, description, project) on the
draft. Pass `version: "new"` to auto-create a draft. The change is only
applied to the live constant when the revision is merged.
tags:
- constant-revisions
parameters:
- name: key
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:
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
name:
description: Short display name. Put details in `description`.
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
description:
description: Markdown. Put context here, not in the name.
type: string
project:
type: string
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConstantRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/constants-revisions/{key}/{version}/metadata'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants-revisions/{key}/{version}/value:
put:
operationId: putConstantRevisionValue
summary: Update the value of a constant draft revision
description: >-
Stages a new default `value` and/or per-environment `environmentValues`
on the draft. At least one must be supplied. Pass `version: "new"` to
auto-create a draft. The value must match the constant's type (valid
JSON for `json` constants).
tags:
- constant-revisions
parameters:
- name: key
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:
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
value:
description: >-
The default value (raw string for `string` constants,
JSON-encoded for `json` constants)
type: string
environmentValues:
description: Per-environment value overrides (environment id → value)
type: object
propertyNames:
type: string
additionalProperties:
type: string
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConstantRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/constants-revisions/{key}/{version}/value'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants-revisions/{key}/{version}/archive:
put:
operationId: putConstantRevisionArchive
summary: Stage an archive/unarchive in a draft revision
description: >-
Stages an archive or unarchive on the draft. Pass `version: "new"` to
auto-create a draft. Archived constants can be permanently deleted via
`DELETE /constants/{key}` once the archive is published.
tags:
- constant-revisions
parameters:
- name: key
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:
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
archived:
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. 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
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. 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
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. 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/ConstantRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/constants-revisions/{key}/{version}/archive'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants-revisions/{key}/{version}/request-review:
post:
operationId: postConstantRevisionRequestReview
summary: Request review for a draft revision
description: >-
Moves the draft from `draft` into `pending-review`. Notifies reviewers
per the org's approval-flow settings.
Set `autoPublishOnApproval` to `true` to publish the revision
automatically the moment it is approved. This requires the org to have
auto-publish-on-approval enabled and the caller to have publish
permission on the constant.
tags:
- constant-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
autoPublishOnApproval:
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. 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
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. 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
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. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConstantRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/constants-revisions/{key}/{version}/request-review'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants-revisions/{key}/{version}/submit-review:
post:
operationId: postConstantRevisionSubmitReview
summary: Submit a review on a draft revision
description: >-
Submits an `approve`, `request-changes`, or `comment` review on the
revision. The verdict belongs to whoever the request acts as; see
[Naming who asked](/api/introduction#naming-who-asked). No one can rule
on a draft they created. Submitting `approve` or `request-changes` needs
Review access. A `comment` is participation rather than a verdict, so it
is also open to the Comments permission or draft authority on the
entity. Authors and contributors cannot submit `approve` reviews on
their own drafts when the org has `blockSelfApproval` enabled.
When `decision` is `approve` and the revision has
`autoPublishOnApproval` enabled, the revision is automatically published
after approval. The response includes `autoPublished: true` when this
happens. Pass `skipAutoPublish: true` to approve without triggering
auto-publish.
tags:
- constant-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
decision:
type: string
enum:
- approve
- request-changes
- comment
comment:
description: Markdown. Why you approved, requested changes or commented.
type: string
skipAutoPublish:
type: boolean
required:
- decision
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConstantRevision'
autoPublished:
type: boolean
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/constants-revisions/{key}/{version}/submit-review'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants-revisions/{key}/{version}/recall-review:
post:
operationId: postConstantRevisionRecallReview
summary: Recall a review request
description: >-
Pulls a revision in review (`pending-review`, `changes-requested`, or
`approved`) back to `draft`, clearing existing reviews and disarming any
auto-publish-on-approval.
tags:
- constant-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConstantRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/constants-revisions/{key}/{version}/recall-review'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants-revisions/{key}/{version}/reopen:
post:
operationId: postConstantRevisionReopen
summary: Reopen a discarded revision
description: >-
Returns a previously discarded revision to `draft` status so it can be
edited and published again. Only discarded revisions can be reopened.
tags:
- constant-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConstantRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/constants-revisions/{key}/{version}/reopen'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants-revisions/{key}/{version}/schedule-publish:
post:
operationId: postConstantRevisionSchedulePublish
summary: Schedule (or cancel) a deferred publish
description: >-
Arms a revision to publish automatically at a future time. Pass
`scheduledPublishAt` as an RFC3339 timestamp in the future to arm, or
`null` to cancel a pending schedule. Requires the `scheduled-revisions`
commercial feature and publish permission on the Constant. A draft that
still requires approval must request review first (or be armed with
`bypassApproval` by a caller who can bypass).
tags:
- constant-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
scheduledPublishAt:
description: >-
When to publish, as an RFC3339 timestamp (e.g.
`2026-01-31T09:00:00Z` or `2026-01-31T02:00:00-07:00`), or
`null` to cancel a pending schedule.
anyOf:
- type: string
format: date-time
- type: 'null'
lockEdits:
type: boolean
lockOthers:
type: boolean
bypassApproval:
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. 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
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. 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
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. 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:
- scheduledPublishAt
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConstantRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/constants-revisions/{key}/{version}/schedule-publish'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants-revisions/{key}/{version}/undo-review:
post:
operationId: postConstantRevisionUndoReview
summary: Retract your own review verdict
description: >-
Retracts the calling user's own active `approve` or `request-changes`
verdict, returning the revision to `pending-review`. Review comments
stay in the log. Retracting a `request-changes` can leave the revision
approved by someone else, in which case an armed auto-publish fires. The
verdict belongs to whoever the request acts as; see [Naming who
asked](/api/introduction#naming-who-asked). No one can rule on a draft
they created.
tags:
- constant-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConstantRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/constants-revisions/{key}/{version}/undo-review'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants-revisions/{key}/{version}/merge-status:
get:
operationId: getConstantRevisionMergeStatus
summary: Get merge status for a draft revision
description: >-
Runs a dry-run merge of the draft against the current live constant and
returns any conflicts. Use this before publishing to preview changes and
detect conflicting edits.
tags:
- constant-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
hasConflicts:
type: boolean
conflicts:
type: array
items:
type: object
properties:
field:
type: string
baseValue: {}
liveValue: {}
proposedValue: {}
required:
- field
- baseValue
- liveValue
- proposedValue
additionalProperties: false
canAutoMerge:
type: boolean
required:
- success
- hasConflicts
- conflicts
- canAutoMerge
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/constants-revisions/{key}/{version}/merge-status'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants-revisions/{key}/{version}/rebase:
post:
operationId: postConstantRevisionRebase
summary: Rebase a draft revision onto the current live constant
description: >-
Updates the draft's base snapshot to the current live state, applying
the draft's changes on top. Supply `conflictResolutions` to resolve any
conflicting fields. Strategies are `overwrite` (use the draft's value)
or `discard` (keep the live value).
tags:
- constant-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
conflictResolutions:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- overwrite
- discard
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConstantRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/constants-revisions/{key}/{version}/rebase'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants-revisions/{key}/{version}/publish:
post:
operationId: postConstantRevisionPublish
summary: Publish a draft revision
description: >-
Publishes the draft and makes its changes live. The caller needs Publish
access for the affected environments. When approval is required, the
draft must be approved unless the caller has Bypass draft approvals
access. If the organization requires rebasing, an out-of-date draft must
be rebased first; an authorized caller can instead send `ignoreWarnings:
true` to force-publish it. A 422 response lists every blocking gate and
the available resolution.
tags:
- constant-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
bypassApproval:
description: >-
Deprecated and ignored. Approval is bypassed automatically
when the caller has Bypass draft approvals access for this
resource or when the organization enables the REST API
approval bypass. Otherwise, the revision must be approved
before it can be published.
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. 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
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. 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
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. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConstantRevision'
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:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/constants-revisions/{key}/{version}/publish'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants-revisions/{key}/{version}/discard:
post:
operationId: postConstantRevisionDiscard
summary: Discard a draft revision
description: >-
Permanently discards a draft revision. Only open revisions (not merged
or already-discarded) can be discarded.
tags:
- constant-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
reason:
type: string
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConstantRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/constants-revisions/{key}/{version}/discard'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/constants-revisions/{key}/{version}/revert:
post:
operationId: postConstantRevisionRevert
summary: Revert the constant to a prior revision
description: >-
Creates a new draft (or immediately publishes) whose content matches the
specified historical revision. Defaults to creating a draft; when the
org enables 'reverts bypass approval' it defaults to publishing
immediately. Pass `strategy` to override.
tags:
- constant-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
strategy:
description: >-
Whether to stage the revert as a draft or publish it
immediately. Defaults to `draft`, or to `publish` when the
org enables 'reverts bypass approval'.
type: string
enum:
- draft
- publish
title:
description: Short draft title (e.g. `Enable for beta testers`).
type: string
comment:
description: Currently ignored. Use `title` to describe the revert.
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
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. 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
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. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConstantRevision'
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:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/constants-revisions/{key}/{version}/revert'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs:
get:
operationId: listConfigs
summary: Get all configs
tags:
- configs
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
configs:
type: array
items:
$ref: '#/components/schemas/Config'
required:
- configs
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/configs' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postConfig
summary: Create a single config
tags:
- configs
parameters:
- $ref: '#/components/parameters/skipSchemaValidation'
- $ref: '#/components/parameters/ignoreWarnings'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
key:
description: >-
Stable reference handle (lowercase slug, unique per org),
referenced as `@config:key`
type: string
pattern: ^[a-z0-9][a-z0-9\-_]*$
name:
description: The display name of the config
type: string
parent:
description: >-
The `key` of the config to inherit from (the primary lineage
spine). Express inheritance via `parent`/`extends`, NEVER
via a `@config:` entry in `value` (which is rejected).
type: string
extends:
description: >-
Additional composition bases (config `key`s) layered on top
of `parent`, in precedence order (later overrides earlier;
all override `parent`; own keys win last). 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: >-
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
description:
description: Markdown. Put context here, not in the name.
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. When
omitted, it defaults to the requesting member: a personal
access token's owner, or the member an organization API key
assumes. An organization API key acting as itself leaves it
empty.
type: string
schema:
description: >-
Field definitions for this config, as a JSON Schema document
(`{ type: "json-schema", value }`) or typed-code source (`{
type: "typescript" | "protobuf" | "python" | "go" | "rust",
value }`) — converted server-side in one call. Fields whose
key an ancestor (via `parent`/`extends`) already owns follow
"base wins": an identical re-declaration is stripped with a
`redundant-declaration` warning; one with a differing
definition is rejected. A field owned by two sibling bases
is a conflict and is rejected. Omit to leave the config
schema-less. Conversion warnings are returned in `warnings`.
$ref: '#/components/schemas/ConfigSchemaSource'
source:
description: >-
Optional identifier of the consuming codebase/service. When
a typed-code schema
(`typescript`/`protobuf`/`python`/`go`/`rust`) is supplied,
its named-type structure is captured under this source so
`GET /configs/:key/schema?source=&format=` can
reproduce those names.
type: string
extensible:
type: boolean
experimentGuard:
description: >-
Enable the experiment guard on this config: publishing a
change served to a running experiment soft-blocks unless
overridden. Omit to inherit the org default.
type: boolean
invariants:
description: >-
Cross-field validation rules. Each rule's expression is a
mongo condition (mongrule). Stored on the config schema and
enforced at publish.
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
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
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. 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
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. 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:
- key
- name
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
required:
- config
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/configs' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"key":"checkout-flow","name":"Checkout Flow","value":{"timeout":30,"retries":3}}'
/v1/configs-revisions:
get:
operationId: listConfigRevisions
summary: List config revisions across the organization
description: >-
Returns a paginated list of revisions across all configs in the
organization, sorted newest-first. Optionally filtered by config,
status, author, or the calling user's involvement.
tags:
- config-revisions
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/skipPagination'
- name: key
in: query
description: >-
Restrict results to revisions for a single config (by its key). When
omitted, returns revisions across every config the caller can read.
schema:
description: >-
Restrict results to revisions for a single config (by its key).
When omitted, returns revisions across every config the caller can
read.
type: string
- name: status
in: query
description: >-
Filter by revision status. Accepts a comma-separated list, or the
literal `open` for non-merged/non-discarded revisions.
schema:
description: >-
Filter by revision status. Accepts a comma-separated list, or the
literal `open` for non-merged/non-discarded revisions.
type: string
- $ref: '#/components/parameters/author'
- name: mine
in: query
description: >-
If true, return only revisions authored by the calling user. Needs a
personal access token, or an organization API key that assumes a
named member's role. Mutually exclusive with `author`.
schema:
description: >-
If true, return only revisions authored by the calling user. Needs
a personal access token, or an organization API key that assumes a
named member's role. Mutually exclusive with `author`.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revisions:
type: array
items:
$ref: '#/components/schemas/ConfigRevision'
limit:
type: integer
offset:
type: integer
count:
type: integer
total:
type: integer
hasMore:
type: boolean
nextOffset:
anyOf:
- type: integer
- type: 'null'
required:
- revisions
- limit
- offset
- count
- total
- hasMore
- nextOffset
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/configs-revisions' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs/{key}/references:
get:
operationId: getConfigReferences
summary: Get features and configs that reference this config
tags:
- configs
parameters:
- name: key
in: path
required: true
description: The key of the config
schema:
description: The key of the config
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
id: ConfigReferences
type: object
properties:
features:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
project:
type: string
required:
- id
additionalProperties: false
constants:
type: array
items:
type: object
properties:
id:
type: string
key:
type: string
name:
type: string
project:
type: string
isConfig:
type: boolean
required:
- id
- key
- name
additionalProperties: false
required:
- features
- constants
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/configs/checkout-flow/references'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs/{key}/key-usage:
get:
operationId: getConfigKeyUsage
summary: Get the feature rules and default values implementing each key
description: >-
Lists every feature rule and default value that overrides a key of this
config's lineage family, so you can see which keys are implemented and
where.
tags:
- configs
parameters:
- name: key
in: path
required: true
description: The key of the config
schema:
description: The key of the config
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
id: ConfigKeyUsage
type: object
properties:
familyKeys:
type: array
items:
type: string
implementations:
type: array
items:
$ref: '#/components/schemas/implementations'
required:
- familyKeys
- implementations
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/configs/checkout-flow/key-usage' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs/{key}/lineage:
get:
operationId: getConfigLineage
summary: Get the full lineage (family tree) for a config
tags:
- configs
parameters:
- name: key
in: path
required: true
description: The key of the config
schema:
description: The key of the config
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
id: ConfigLineage
type: object
properties:
root:
description: The key of the family root (the topmost ancestor).
type: string
target:
description: The requested config's key.
type: string
ancestors:
description: >-
The target's ancestor keys, root-first, ending at its
immediate parent.
type: array
items:
type: string
descendants:
description: Keys of every config that descends from the target.
type: array
items:
type: string
nodes:
description: >-
Every config in the family (root plus all descendants),
breadth-first.
type: array
items:
$ref: '#/components/schemas/nodes'
required:
- root
- target
- ancestors
- descendants
- nodes
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/configs/checkout-flow/lineage' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs/{key}/schema/verify:
post:
operationId: verifyConfigSchema
summary: Verify a config's schema against a source (drift check)
tags:
- configs
parameters:
- name: key
in: path
required: true
description: The key of the config
schema:
description: The key of the config
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
schema:
description: >-
The schema to check against the config's stored schema — a
JSON Schema document or typed-code source
(`typescript`/`protobuf`/`python`/`go`/`rust`). Read-only:
nothing is mutated.
$ref: '#/components/schemas/ConfigSchemaSource'
required:
- schema
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
id: ConfigSchemaVerify
type: object
properties:
inSync:
description: >-
True when the supplied schema is canonically identical to
the config's stored schema.
type: boolean
fingerprint:
description: Canonical fingerprint of the config's stored schema.
type: string
incomingFingerprint:
description: Canonical fingerprint of the supplied schema.
type: string
drift:
$ref: '#/components/schemas/drift'
ancestorOwnedFields:
description: >-
Supplied fields an ancestor config already owns ("base
wins"). Subtract these from `drift.contract` adds when
round-tripping a full effective schema.
type: array
items:
$ref: '#/components/schemas/ancestorOwnedFields'
warnings:
type: array
items:
$ref: '#/components/schemas/ConfigSchemaWarning'
required:
- inSync
- fingerprint
- incomingFingerprint
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/configs/checkout-flow/schema/verify'
\
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"schema":{"type":"typescript","value":"interface CheckoutFlow { timeout: number; retries: number }"}}'
/v1/configs/{key}/schema:
get:
operationId: getConfigSchema
summary: Export a config's schema
tags:
- configs
parameters:
- name: key
in: path
required: true
description: The key of the config
schema:
description: The key of the config
type: string
- name: format
in: query
description: >-
Output format. `json-schema` (default) returns a JSON Schema
document; `typescript`, `protobuf`, `python` (Pydantic), `go`, and
`rust` (serde) render the schema as source in that language.
schema:
description: >-
Output format. `json-schema` (default) returns a JSON Schema
document; `typescript`, `protobuf`, `python` (Pydantic), `go`, and
`rust` (serde) render the schema as source in that language.
type: string
enum:
- json-schema
- typescript
- protobuf
- python
- go
- rust
- $ref: '#/components/parameters/effective'
- $ref: '#/components/parameters/source'
responses:
'200':
description: Successful response
content:
application/json:
schema:
id: ConfigSchemaExport
type: object
properties:
schema:
description: >-
The config's schema in the requested format: a JSON Schema
document (`{ type: "json-schema", value }`) or rendered
TypeScript source (`{ type: "typescript", value }`).
$ref: '#/components/schemas/ConfigSchemaSource'
effective:
description: >-
True when the schema includes inherited fields accumulated
across the lineage; false when it is only this config's
own fields.
type: boolean
additionalProperties:
description: Whether the config family permits extra keys.
type: boolean
required:
- schema
- effective
- additionalProperties
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/configs/checkout-flow/schema' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs/{key}:
get:
operationId: getConfig
summary: Get a single config
tags:
- configs
parameters:
- name: key
in: path
required: true
description: The key of the config
schema:
description: The key of the config
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
config:
$ref: '#/components/schemas/Config'
required:
- config
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET 'https://api.growthbook.io/api/v1/configs/checkout-flow'
\
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: updateConfig
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.
tags:
- configs
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:
description: Short display name. Put details in `description`.
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:
description: Markdown. Put context here, not in the name.
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:
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`.
$ref: '#/components/schemas/ConfigSchemaSource'
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. 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
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. 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
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. 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
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
'202':
$ref: '#/components/responses/ConfirmationHeld'
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}}'
delete:
operationId: deleteConfig
summary: Delete a single config
tags:
- configs
parameters:
- name: key
in: path
required: true
description: The key of the config
schema:
description: The key of the config
type: string
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/configs/checkout-flow' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs/{key}/archive:
post:
operationId: archiveConfig
summary: Archive a single config
description: >-
Archives a config. A child config (including an environment/project
override) is archived outright when its live value is an empty patch or
nothing serves it. When archiving would strip a value that live features
or other configs still consume, the request returns a 422 listing the
blocking gates — re-submit with `"ignoreWarnings": true` in the request
body to acknowledge and proceed. A locked config, or one whose org
requires approval, returns its own gate (unlock or route the change
through a draft revision).
tags:
- configs
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/ignoreWarnings'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
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
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. 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
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. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
config:
$ref: '#/components/schemas/Config'
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
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/configs/checkout-flow/archive' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs/{key}/unarchive:
post:
operationId: unarchiveConfig
summary: Unarchive a single config
tags:
- configs
parameters:
- name: key
in: path
required: true
description: The key of the config
schema:
description: The key of the config
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
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
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. 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
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. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
config:
$ref: '#/components/schemas/Config'
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
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/configs/checkout-flow/unarchive' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs/{key}/lock:
post:
operationId: lockConfig
summary: Lock a config at its current published revision
description: >-
Locks the Config to its current published revision. Drafts can still be
created and edited, but direct updates, publishes, scheduled publishes,
reverts, and archives are blocked. The response returns the pinned
revision in `lockedRevision`. Unlocking requires Bypass draft approvals
access.
tags:
- configs
parameters:
- name: key
in: path
required: true
description: The key of the config
schema:
description: The key of the config
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
reason:
description: Optional note explaining why the config was locked.
type: string
maxLength: 10000
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
config:
$ref: '#/components/schemas/Config'
required:
- config
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/configs/checkout-flow/lock' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs/{key}/unlock:
post:
operationId: unlockConfig
summary: Unlock a config
description: >-
Removes the Config lock so changes can be published again. The caller
must have Bypass draft approvals access in the Config's Project.
tags:
- configs
parameters:
- name: key
in: path
required: true
description: The key of the config
schema:
description: The key of the config
type: string
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
config:
$ref: '#/components/schemas/Config'
required:
- config
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/configs/checkout-flow/unlock' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}:
get:
operationId: getConfigRevisions
summary: List revisions for a config
description: >-
Returns a paginated list of revisions for this config, sorted
newest-first. Optionally filtered by status, author, or the calling
user's involvement.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/skipPagination'
- name: status
in: query
description: >-
Filter by revision status. Accepts a comma-separated list, or the
literal `open` for non-merged/non-discarded revisions.
schema:
description: >-
Filter by revision status. Accepts a comma-separated list, or the
literal `open` for non-merged/non-discarded revisions.
type: string
- $ref: '#/components/parameters/author'
- name: mine
in: query
description: >-
If true, return only revisions authored by the calling user. Needs a
personal access token, or an organization API key that assumes a
named member's role. Mutually exclusive with `author`.
schema:
description: >-
If true, return only revisions authored by the calling user. Needs
a personal access token, or an organization API key that assumes a
named member's role. Mutually exclusive with `author`.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revisions:
type: array
items:
$ref: '#/components/schemas/ConfigRevision'
limit:
type: integer
offset:
type: integer
count:
type: integer
total:
type: integer
hasMore:
type: boolean
nextOffset:
anyOf:
- type: integer
- type: 'null'
required:
- revisions
- limit
- offset
- count
- total
- hasMore
- nextOffset
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/configs-revisions/checkout-flow' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postConfigRevision
summary: Create a draft revision
description: >-
Creates a new draft revision branched from the current live config. A
config can have multiple concurrent drafts; use this to start an
isolated line of edits.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
type: string
comment:
type: string
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/configs-revisions/{key}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}/latest:
get:
operationId: getConfigRevisionLatest
summary: Get the most recent active draft revision
description: >-
Returns the most recently updated open (non-merged, non-discarded)
revision for the config. Returns 404 if there is no active draft. Pass
`mine=true` to restrict to drafts authored by the calling user. Needs a
personal access token, or an organization API key that assumes a named
member's role.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- name: mine
in: query
description: >-
If true, return only the most recent active draft authored by the
calling user. Needs a personal access token, or an organization API
key that assumes a named member's role.
schema:
description: >-
If true, return only the most recent active draft authored by the
calling user. Needs a personal access token, or an organization
API key that assumes a named member's role.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/configs-revisions/checkout-flow/latest'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}/{version}:
get:
operationId: getConfigRevision
summary: Get a single config revision
description: >-
Returns the revision at the specified version for this config. Use `GET
/configs-revisions/{key}/latest` for the most recent active draft.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/configs-revisions/checkout-flow/3'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}/{version}/metadata:
put:
operationId: putConfigRevisionMetadata
summary: Update config metadata in a draft revision
description: >-
Stages metadata changes (name, owner, description, project, lineage
parent, extensibility) on the draft. Pass `version: "new"` to
auto-create a draft. The change is only applied to the live config when
the revision is merged.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- name: version
in: path
required: true
description: ''
schema:
anyOf:
- type: integer
- type: string
const: new
- $ref: '#/components/parameters/skipSchemaValidation'
- $ref: '#/components/parameters/ignoreWarnings'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
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
name:
description: Short display name. Put details in `description`.
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
description:
description: Markdown. Put context here, not in the name.
type: string
project:
type: string
parent:
description: >-
Change the lineage parent (the `key` to inherit from). Empty
string detaches from the parent.
type: string
extends:
description: >-
Replace the composition 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.
type: array
items:
type: string
extensible:
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. 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
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. 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
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. 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
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
warnings:
type: array
items:
$ref: '#/components/schemas/ConfigSchemaWarning'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/metadata'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}/{version}/value:
put:
operationId: putConfigRevisionValue
summary: Update the value of a config draft revision
description: >-
Stages a new `value` (this config's own JSON object) on the draft. Pass
`version: "new"` to auto-create a draft. A `@config:` inheritance entry
in the value is rejected — express lineage via the `parent`/`extends`
metadata fields instead. Configs are environment-agnostic: there is no
per-environment override (use a Constant for that).
Inheritance is a deep (targeted) patch: this value is merged onto the
resolved parent recursively, key by key — restate only the leaves you
want to change and the rest are inherited. Arrays and scalars replace
wholesale, `null` is a value (it does not delete a key), and a value
composed from a constant via `$extends` is applied whole.
Set `inferSchemaIfMissing: true` to derive and stage a field schema from
the value when the config has none yet.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- name: version
in: path
required: true
description: ''
schema:
anyOf:
- type: integer
- type: string
const: new
- $ref: '#/components/parameters/skipSchemaValidation'
- $ref: '#/components/parameters/ignoreWarnings'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
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
value:
description: >-
This config's own value as a JSON object — a targeted patch
deep-merged onto the resolved parent value.
type: object
propertyNames:
type: string
additionalProperties: {}
inferSchemaIfMissing:
description: >-
When the config has no schema yet, infer one from the
supplied `value` and stage it on the same draft.
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. 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
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. 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
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. 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
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
warnings:
type: array
items:
$ref: '#/components/schemas/ConfigSchemaWarning'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/value'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}/{version}/property:
put:
operationId: putConfigRevisionProperty
summary: Set one property of a config draft revision's value
description: >-
Stages a single property of this config's own value on the draft,
leaving every other property untouched. Prefer this over `PUT .../value`
when changing one field: a whole-value write from a stale read silently
drops properties someone else added in the meantime.
`null` is a value (it does not remove the property) — use `DELETE
.../property` to remove one. Pass `version: "new"` to auto-create a
draft.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- name: version
in: path
required: true
description: ''
schema:
anyOf:
- type: integer
- type: string
const: new
- $ref: '#/components/parameters/skipSchemaValidation'
- $ref: '#/components/parameters/ignoreWarnings'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
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
property:
description: Name of the property to set in this config's own value.
type: string
value:
description: The property's new value. `null` sets it to null.
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
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. 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
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. 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:
- property
- value
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
warnings:
type: array
items:
$ref: '#/components/schemas/ConfigSchemaWarning'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/property'
\
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteConfigRevisionProperty
summary: Remove one property from a config draft revision's value
description: >-
Stages removal of a single property from this config's own value on the
draft; the config then inherits that property from its parent (if any).
Every other property is untouched. Pass `version: "new"` to auto-create
a draft.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- name: version
in: path
required: true
description: ''
schema:
anyOf:
- type: integer
- type: string
const: new
- name: property
in: query
required: true
description: Name of the property to remove.
schema:
description: Name of the property to remove.
type: string
- $ref: '#/components/parameters/skipSchemaValidation'
- $ref: '#/components/parameters/ignoreWarnings'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/property'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}/{version}/schema:
put:
operationId: putConfigRevisionSchema
summary: Update or import the schema of a config draft revision
description: >-
Stages this config's field schema on the draft. Provide exactly ONE
source:
- `schema`: a schema document — `{ type: "json-schema", value }` (a JSON
Schema object) or `{ type: "typescript", value }` (TypeScript source).
**JSON Schema is the recommended ("happy path") format** — it is the
canonical pivot, preserves nested objects/arrays, and resolves local
`$ref`/`$defs` (so generator output with referenced types works).
`typescript` is a best-effort convenience parser. All conversions are
lossy-by-design and degrade exotic constructs to permissive types WITH
warnings (returned in `warnings`).
- `infer: true`: derive the schema from the draft's 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. Pass `version:
"new"` to auto-create a draft.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- name: version
in: path
required: true
description: ''
schema:
anyOf:
- type: integer
- type: string
const: new
- $ref: '#/components/parameters/skipSchemaValidation'
- $ref: '#/components/parameters/ignoreWarnings'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
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
schema:
$ref: '#/components/schemas/ConfigSchemaSource'
infer:
description: Derive the schema from the draft's value instead.
type: boolean
additionalProperties:
description: >-
Whether the resulting object schema permits extra keys
(family extensibility).
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. 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
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. 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
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. 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
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
warnings:
type: array
items:
$ref: '#/components/schemas/ConfigSchemaWarning'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/schema'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}/{version}/projection:
put:
operationId: putConfigRevisionProjection
summary: Set (or update) a config's per-source render projection on a draft
description: >-
Stages a per-source render projection on the draft, AND the schema it
implies. Provide a named `schema` source (`{ type: "typescript" |
"protobuf" | "python" | "go" | "rust" | "json-schema", value }`) for the
consuming codebase identified by `source`: GrowthBook derives the
config's canonical schema from it (so the change projects into the
Config) and captures that source's named-type structure under
`renderProjections[source]`. Both are staged on the draft and published
through the normal flow. Pass `version: "new"` to auto-create a draft.
Lossy conversions degrade with `warnings`.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- name: version
in: path
required: true
description: ''
schema:
anyOf:
- type: integer
- type: string
const: new
- $ref: '#/components/parameters/skipSchemaValidation'
- $ref: '#/components/parameters/ignoreWarnings'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
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
source:
description: >-
Identifier of the consuming codebase/service this projection
belongs to.
type: string
schema:
description: >-
The named schema source for this projection. Its type names
are captured; its structure derives the config's canonical
schema.
$ref: '#/components/schemas/ConfigSchemaSource'
additionalProperties:
description: >-
Whether the resulting object schema permits extra keys
(family extensibility).
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. 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
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. 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
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. 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:
- source
- schema
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
warnings:
type: array
items:
$ref: '#/components/schemas/ConfigSchemaWarning'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/projection'
\
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteConfigRevisionProjection
summary: Remove a config's per-source render projection on a draft
description: >-
Stages removal of the `source` projection from `renderProjections` on
the draft (the canonical schema is unchanged). Published through the
normal flow. Pass `version: "new"` to auto-create a draft.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- name: version
in: path
required: true
description: ''
schema:
anyOf:
- type: integer
- type: string
const: new
- name: source
in: query
required: true
description: Identifier of the projection (source) to remove.
schema:
description: Identifier of the projection (source) to remove.
type: string
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/projection'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}/{version}/archive:
put:
operationId: putConfigRevisionArchive
summary: Stage an archive/unarchive in a draft revision
description: >-
Stages an archive or unarchive on the draft. Pass `version: "new"` to
auto-create a draft. Archived configs can be permanently deleted via
`DELETE /configs/{key}` once the archive is published.
tags:
- config-revisions
parameters:
- name: key
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:
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
archived:
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. 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
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. 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
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. 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/ConfigRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/archive'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}/{version}/request-review:
post:
operationId: postConfigRevisionRequestReview
summary: Request review for a draft revision
description: >-
Moves the draft from `draft` into `pending-review`. Notifies reviewers
per the org's approval-flow settings.
Set `autoPublishOnApproval` to `true` to publish the revision
automatically the moment it is approved. This requires the org to have
auto-publish-on-approval enabled and the caller to have publish
permission on the config.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
autoPublishOnApproval:
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. 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
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. 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
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. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/request-review'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}/{version}/submit-review:
post:
operationId: postConfigRevisionSubmitReview
summary: Submit a review on a draft revision
description: >-
Submits an `approve`, `request-changes`, or `comment` review on the
revision. The verdict belongs to whoever the request acts as; see
[Naming who asked](/api/introduction#naming-who-asked). No one can rule
on a draft they created. Submitting `approve` or `request-changes` needs
Review access. A `comment` is participation rather than a verdict, so it
is also open to the Comments permission or draft authority on the
entity. Authors and contributors cannot submit `approve` reviews on
their own drafts when the org has `blockSelfApproval` enabled.
When `decision` is `approve` and the revision has
`autoPublishOnApproval` enabled, the revision is automatically published
after approval. The response includes `autoPublished: true` when this
happens. Pass `skipAutoPublish: true` to approve without triggering
auto-publish.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
decision:
type: string
enum:
- approve
- request-changes
- comment
comment:
description: Markdown. Why you approved, requested changes or commented.
type: string
skipAutoPublish:
type: boolean
required:
- decision
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
autoPublished:
type: boolean
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/submit-review'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}/{version}/undo-review:
post:
operationId: postConfigRevisionUndoReview
summary: Retract your own review verdict
description: >-
Retracts the calling user's own active `approve` or `request-changes`
verdict, returning the revision to `pending-review`. Review comments
stay in the log. Retracting a `request-changes` can leave the revision
approved by someone else, in which case an armed auto-publish fires. The
verdict belongs to whoever the request acts as; see [Naming who
asked](/api/introduction#naming-who-asked). No one can rule on a draft
they created.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/undo-review'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}/{version}/recall-review:
post:
operationId: postConfigRevisionRecallReview
summary: Recall a review request
description: >-
Pulls a revision in review (`pending-review`, `changes-requested`, or
`approved`) back to `draft`, clearing existing reviews and disarming any
auto-publish-on-approval.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/recall-review'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}/{version}/reopen:
post:
operationId: postConfigRevisionReopen
summary: Reopen a discarded revision
description: >-
Returns a previously discarded revision to `draft` status so it can be
edited and published again. Only discarded revisions can be reopened.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties: {}
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/reopen'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}/{version}/schedule-publish:
post:
operationId: postConfigRevisionSchedulePublish
summary: Schedule (or cancel) a deferred publish
description: >-
Arms a revision to publish automatically at a future time. Pass
`scheduledPublishAt` as an RFC3339 timestamp in the future to arm, or
`null` to cancel a pending schedule. Requires the `scheduled-revisions`
commercial feature and publish permission on the config. A draft that
still requires approval must request review first (or be armed with
`bypassApproval` by a caller who can bypass).
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
scheduledPublishAt:
description: >-
When to publish, as an RFC3339 timestamp (e.g.
`2026-01-31T09:00:00Z` or `2026-01-31T02:00:00-07:00`), or
`null` to cancel a pending schedule.
anyOf:
- type: string
format: date-time
- type: 'null'
lockEdits:
type: boolean
lockOthers:
type: boolean
bypassApproval:
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. 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
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. 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
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. 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:
- scheduledPublishAt
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/schedule-publish'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}/{version}/merge-status:
get:
operationId: getConfigRevisionMergeStatus
summary: Get merge status for a draft revision
description: >-
Runs a dry-run merge of the draft against the current live config and
returns any conflicts. Use this before publishing to preview changes and
detect conflicting edits.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
hasConflicts:
type: boolean
conflicts:
type: array
items:
type: object
properties:
field:
type: string
baseValue: {}
liveValue: {}
proposedValue: {}
required:
- field
- baseValue
- liveValue
- proposedValue
additionalProperties: false
canAutoMerge:
type: boolean
required:
- success
- hasConflicts
- conflicts
- canAutoMerge
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/merge-status'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}/{version}/rebase:
post:
operationId: postConfigRevisionRebase
summary: Rebase a draft revision onto the current live config
description: >-
Updates the draft's base snapshot to the current live state, applying
the draft's changes on top. Supply `conflictResolutions` to resolve any
conflicting fields. Strategies are `overwrite` (use the draft's value),
`discard` (keep the live value), or `union` (merge arrays without
duplicates — for array fields like `extends`; pass a `customValues`
entry to supply the resolved array yourself).
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
conflictResolutions:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- overwrite
- discard
- union
customValues:
description: >-
Custom values to use for `union` strategy fields. Keyed by
field name.
type: object
propertyNames:
type: string
additionalProperties:
type: array
items: {}
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/rebase'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}/{version}/publish:
post:
operationId: postConfigRevisionPublish
summary: Publish a draft revision
description: >-
Publishes the draft and makes its changes live. The caller needs Publish
access for the affected environments. When approval is required, the
draft must be approved unless the caller has Bypass draft approvals
access. If the organization requires rebasing, an out-of-date draft must
be rebased first; an authorized caller can instead send `ignoreWarnings:
true` to force-publish it. A locked Config cannot be published. A 422
response lists every blocking gate and the available resolution.
Publishing a schema change also normalizes descendant Configs according
to their inheritance rules.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
- $ref: '#/components/parameters/skipSchemaValidation'
- $ref: '#/components/parameters/ignoreWarnings'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
bypassApproval:
description: >-
Deprecated and ignored. Approval is bypassed automatically
when the caller has Bypass draft approvals access for this
resource or when the organization enables the REST API
approval bypass. Otherwise, the revision must be approved
before it can be published.
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. 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
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. 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
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. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
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:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/publish'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}/{version}/discard:
post:
operationId: postConfigRevisionDiscard
summary: Discard a draft revision
description: >-
Permanently discards a draft revision. Only open revisions (not merged
or already-discarded) can be discarded.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
reason:
type: string
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
required:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/discard'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/configs-revisions/{key}/{version}/revert:
post:
operationId: postConfigRevisionRevert
summary: Revert the config to a prior revision
description: >-
Creates a new draft (or immediately publishes) whose content matches the
specified historical revision. Defaults to creating a draft; when the
org enables 'reverts bypass approval' it defaults to publishing
immediately. Pass `strategy` to override.
tags:
- config-revisions
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
- $ref: '#/components/parameters/skipSchemaValidation'
- $ref: '#/components/parameters/ignoreWarnings'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
strategy:
description: >-
Whether to stage the revert as a draft or publish it
immediately. Defaults to `draft`, or to `publish` when the
org enables 'reverts bypass approval'.
type: string
enum:
- draft
- publish
title:
description: Short draft title (e.g. `Enable for beta testers`).
type: string
comment:
description: Currently ignored. Use `title` to describe the revert.
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
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. 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
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. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/ConfigRevision'
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:
- revision
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/revert'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/releases/publish-revisions:
post:
operationId: postReleasePublishRevisions
summary: Atomically publish revisions across multiple entities
description: >-
Publishes a set of revisions — at most one per entity — across Feature
Flags, Saved Groups, configs, and constants as a single all-or-nothing
operation.
Validation, guards, and custom hooks run against the combined end-state
of the whole set, so interdependent changes (e.g. a config schema change
plus the values that depend on it) publish together even when the
in-between states would be invalid.
A blocked publish returns one 422 listing every gate across every item
and the flag that clears each. A concurrent change to any target aborts
with a 409 and nothing publishes. A failure after the commit starts
rolls everything back and emits `revision.publishFailed` for each
revision in the set. SDK payloads refresh once per request. Pass
`dryRun: true` for the full gate report with zero writes.
Requires the `releases` commercial feature.
tags:
- releases
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
revisions:
description: The revisions to publish, at most one per entity.
minItems: 1
maxItems: 50
type: array
items:
anyOf:
- title: Feature Revision Ref
$ref: '#/components/schemas/FeatureRevisionRef'
- title: Saved Group Revision Ref
$ref: '#/components/schemas/SavedGroupRevisionRef'
- title: Config Revision Ref
$ref: '#/components/schemas/ConfigRevisionRef'
- title: Constant Revision Ref
$ref: '#/components/schemas/ConstantRevisionRef'
- title: Revision Id Ref
$ref: '#/components/schemas/RevisionIdRef'
dryRun:
description: Report every gate and outcome without writing anything.
type: boolean
ignoreWarnings:
description: >-
Set to true to acknowledge warnings from experiment guards,
schema changes, or archives. It can also force-publish an
out-of-date draft when the caller has Bypass draft approvals
access for that resource. 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
skipSchemaValidation:
description: >-
Set to true to publish despite schema or invariant failures.
Validation still runs and the response still reports each
failure. The caller must have Bypass draft approvals access
for Feature Flags, Configs, and Constants in every Project.
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
skipHooks:
description: >-
Set to true to publish despite Custom Hook rejections. The
caller must have Bypass draft approvals access for Feature
Flags, Configs, and Constants in every Project. 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
comment:
description: >-
An optional publish comment recorded on every revision in
this release — it appears in each entity's revision history
and is passed to any custom validation hooks that run for
the publish.
type: string
required:
- revisions
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
dryRun:
type: boolean
bulkPublishId:
description: >-
Correlation token (`pub_…`) stamped on every event this
publish emitted. Absent on dry runs.
type: string
results:
type: array
items:
$ref: '#/components/schemas/results'
gates:
description: >-
Dry runs report every gate, cleared and blocking. Real
publishes return an empty list — blocking gates fail with
a 422 instead.
type: array
items:
type: object
properties:
entityType:
type: string
enum:
- feature
- saved-group
- config
- constant
id:
description: The identifier used in the request.
type: string
version:
type: integer
type:
description: Gate kind, e.g. "approval-required".
type: string
severity:
type: string
enum:
- blocker
- warning
messages:
type: array
items:
type: string
override:
description: Request flag that clears this gate on retry, if any.
anyOf:
- type: string
- type: 'null'
requiresPermission:
anyOf:
- type: string
- type: 'null'
resolution:
description: >-
A route that resolves the gate without an override
flag.
anyOf:
- type: object
properties:
action:
type: string
method:
type: string
path:
type: string
required:
- action
- method
- path
additionalProperties: false
- type: 'null'
required:
- entityType
- id
- version
- type
- severity
- messages
- override
- requiresPermission
- resolution
additionalProperties: false
bypassedGates:
description: >-
Gates bypassed by the caller's flags or authority — what
this publish overrode.
type: array
items:
type: object
properties:
entityType:
type: string
enum:
- feature
- saved-group
- config
- constant
id:
type: string
version:
type: integer
type:
type: string
via:
description: >-
How the gate was bypassed: a request field, the
caller's permissions, or the organization's REST API
approval-bypass setting.
type: string
required:
- entityType
- id
- version
- type
- via
additionalProperties: false
warnings:
type: array
items:
type: string
required:
- dryRun
- results
- gates
- bypassedGates
- warnings
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/releases/publish-revisions' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/custom-hooks:
get:
operationId: listCustomHooks
summary: Get all custom hooks
tags:
- custom-hooks
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
customHooks:
type: array
items:
$ref: '#/components/schemas/CustomHook'
required:
- customHooks
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/custom-hooks' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postCustomHook
summary: Create a single custom hook
tags:
- custom-hooks
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: The display name of the custom hook
type: string
hook:
type: string
enum:
- validateFeature
- validateFeatureRevision
- validateConfig
- validateConfigRevision
- validateExperiment
code:
type: string
enabled:
default: true
type: boolean
projects:
description: Project ids the hook applies to (empty/omitted = all)
type: array
items:
type: string
entityType:
type: string
enum:
- feature
- config
- experiment
entityId:
type: string
incrementalChangesOnly:
type: boolean
required:
- name
- hook
- code
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
customHook:
$ref: '#/components/schemas/CustomHook'
required:
- customHook
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/custom-hooks' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"name":"Require a description","hook":"validateFeature","code":"if (!feature.description) {\n throw new Error(\"Feature must have a description\");\n}"}'
/v1/custom-hooks/test:
post:
operationId: testCustomHook
summary: Dry-run hook code in the sandbox
tags:
- custom-hooks
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
functionBody:
description: JavaScript function body to execute in the sandbox
type: string
functionArgs:
description: >-
Arguments exposed to the function as named globals (e.g.
`feature`, `config`, `revision`)
type: object
propertyNames:
type: string
additionalProperties: {}
originalFunctionArgs:
description: >-
State before the change. When supplied, the hook also runs
against it and Incremental Changes Only suppression is
applied to the result.
type: object
propertyNames:
type: string
additionalProperties: {}
entityType:
type: string
enum:
- feature
- config
- experiment
entityId:
type: string
required:
- functionBody
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
returnVal:
description: JSON-stringified return value, when the hook returned one
type: string
error:
type: string
warnings:
type: array
items:
type: string
log:
description: Captured console output
type: string
suppressed:
$ref: '#/components/schemas/suppressed'
required:
- success
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/custom-hooks/test' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"functionBody":"if (!feature.description) throw new Error(\"No description\");","functionArgs":{"feature":{"id":"my-feature","description":""}}}'
/v1/custom-hooks/{id}:
get:
operationId: getCustomHook
summary: Get a single custom hook
tags:
- custom-hooks
parameters:
- name: id
in: path
required: true
description: The id of the custom hook
schema:
description: The id of the custom hook
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
customHook:
$ref: '#/components/schemas/CustomHook'
required:
- customHook
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/custom-hooks/hook_123abc' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: updateCustomHook
summary: Partially update a single custom hook
tags:
- custom-hooks
parameters:
- name: id
in: path
required: true
description: The id of the custom hook
schema:
description: The id of the custom hook
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
hook:
type: string
enum:
- validateFeature
- validateFeatureRevision
- validateConfig
- validateConfigRevision
- validateExperiment
code:
type: string
enabled:
type: boolean
projects:
type: array
items:
type: string
entityType:
description: >-
Retarget the hook's scope (set with entityId). Pass null
(with entityId: null) to make the hook
global/project-scoped; omit to leave unchanged.
anyOf:
- type: string
enum:
- feature
- config
- experiment
- type: 'null'
entityId:
description: >-
The scoped resource: a feature id, or a config key. Pass
null (with entityType: null) to clear the scope; omit to
leave unchanged.
anyOf:
- type: string
- type: 'null'
incrementalChangesOnly:
type: boolean
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
customHook:
$ref: '#/components/schemas/CustomHook'
required:
- customHook
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/custom-hooks/hook_123abc' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"enabled":false}'
delete:
operationId: deleteCustomHook
summary: Delete a single custom hook
tags:
- custom-hooks
parameters:
- name: id
in: path
required: true
description: The id of the custom hook
schema:
description: The id of the custom hook
type: string
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/custom-hooks/hook_123abc' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/custom-hooks/{id}/history:
get:
operationId: listCustomHookHistory
summary: List a custom hook's version history
tags:
- custom-hooks
parameters:
- name: id
in: path
required: true
description: The id of the custom hook
schema:
description: The id of the custom hook
type: string
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
versions:
type: array
items:
$ref: '#/components/schemas/versions'
required:
- versions
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/custom-hooks/hook_123abc/history'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/custom-hooks/{id}/revert:
post:
operationId: revertCustomHook
summary: Revert a custom hook to a previous version
tags:
- custom-hooks
parameters:
- name: id
in: path
required: true
description: The id of the custom hook
schema:
description: The id of the custom hook
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
auditId:
description: The version to restore (from the history endpoint)
type: string
required:
- auditId
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
customHook:
$ref: '#/components/schemas/CustomHook'
required:
- customHook
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/custom-hooks/hook_123abc/revert' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"auditId":"aud_123abc"}'
/v1/organizations:
get:
operationId: listOrganizations
summary: >-
Get all organizations (only for super admins on multi-org Enterprise
Plan only)
tags:
- organizations
parameters:
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
organizations:
type: array
items:
$ref: '#/components/schemas/Organization'
required:
- organizations
additionalProperties: false
- type: object
properties:
limit:
type: integer
offset:
type: integer
count:
type: integer
total:
type: integer
hasMore:
type: boolean
nextOffset:
anyOf:
- type: integer
- type: 'null'
required:
- limit
- offset
- count
- total
- hasMore
- nextOffset
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/organizations' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postOrganization
summary: >-
Create a single organization (only for super admins on multi-org
Enterprise Plan only)
tags:
- organizations
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: The name of the organization
type: string
externalId:
description: >-
An optional identifier that you use within your company for
the organization
type: string
required:
- name
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
organization:
$ref: '#/components/schemas/Organization'
required:
- organization
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/organizations' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"name":"My Subsidiary"}'
/v1/organizations/{id}:
put:
operationId: putOrganization
summary: >-
Edit a single organization (only for super admins on multi-org
Enterprise Plan only)
tags:
- organizations
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: The name of the organization
type: string
externalId:
description: >-
An optional identifier that you use within your company for
the organization
type: string
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
organization:
$ref: '#/components/schemas/Organization'
required:
- organization
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT 'https://api.growthbook.io/api/v1/organizations/abc123'
\
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"name":"My Subsidiary","externalId":"subsidiary-123"}'
/v1/sdk-payload/{key}:
get:
operationId: getSdkPayload
summary: Get a SDK payload
parameters:
- name: key
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema: {}
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/sdk-payload/{key}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/fact-tables:
get:
operationId: listFactTables
summary: Get all fact tables
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/datasourceId'
- $ref: '#/components/parameters/projectId'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
factTables:
type: array
items:
$ref: '#/components/schemas/FactTable'
required:
- factTables
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/fact-tables' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postFactTable
summary: Create a single fact table
tags:
- fact-tables
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name. Put details in `description`.
type: string
description:
description: Markdown. Put context here, not in the name.
type: string
maxLength: 10000
owner:
description: >-
The userId or email address of the owner. If an email
address is provided, it will be used to look up the userId
of the matching organization member. If an ID is provided,
it will be validated as existing in the organization.
type: string
projects:
description: List of associated project ids
type: array
items:
type: string
tags:
description: List of associated tags
type: array
items:
type: string
datasource:
description: The datasource id
type: string
userIdTypes:
description: >-
List of identifier columns in this table. For example, "id"
or "anonymous_id"
type: array
items:
type: string
userIdColumns:
description: >-
Maps an identifier type to the column holding it, for SQL
that does not alias its columns to the identifier type
names, e.g. `{"user_id": "userId"}`. May also be a
single-level field path into a JSON column
(`properties.userId`). Unmapped types use the identifier
type name as the column name.
type: object
propertyNames:
type: string
additionalProperties:
type: string
aggregatedFactTableSettings:
description: >-
Settings for maintaining shared daily aggregated tables (a
subset of userIdTypes plus the daily update time and restate
lookback window) used to speed up CUPED. Requires the data
pipeline (pipeline-mode) feature.
type: object
properties:
idTypes:
type: array
items:
type: string
updateTime:
type: object
properties:
time:
type: string
timezone:
type: string
required:
- time
- timezone
additionalProperties: false
lookbackWindow:
type: integer
exclusiveMinimum: 0
restateChunkDays:
type: integer
minimum: 1
maximum: 7
required:
- idTypes
- updateTime
- lookbackWindow
additionalProperties: false
sql:
description: The SQL query for this fact table
type: string
timestampColumn:
description: >-
The column holding the event timestamp. Must be a date
column on this fact table. Defaults to "timestamp" when
unset.
type: string
eventName:
description: The event name used in SQL template variables
type: string
columns:
description: >-
Optional array of column definitions to store for this fact
table. Supplied columns are stored as-is. Omit `datatype`
(or send "") on a column to have it auto-detected from the
SQL.
type: array
items:
$ref: '#/components/schemas/FactTableColumnInput'
managedBy:
description: >-
Set this to "api" (or "dbt" for resources synced from dbt)
to disable editing in the GrowthBook UI
type: string
enum:
- ''
- api
- admin
- dbt
required:
- name
- datasource
- userIdTypes
- sql
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
factTable:
$ref: '#/components/schemas/FactTable'
required:
- factTable
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/fact-tables' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"name":"Orders","datasource":"ds_abc123","userIdTypes":["id"],"sql":"SELECT * FROM orders"}'
/v1/fact-tables/{id}:
get:
operationId: getFactTable
summary: Get a single fact table
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
factTable:
$ref: '#/components/schemas/FactTable'
required:
- factTable
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/fact-tables/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: updateFactTable
summary: Update a single fact table
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name. Put details in `description`.
type: string
description:
description: Markdown. Put context here, not in the name.
type: string
maxLength: 10000
owner:
description: >-
The userId or email address of the owner. If an email
address is provided, it will be used to look up the userId
of the matching organization member. If an ID is provided,
it will be validated as existing in the organization.
type: string
projects:
description: List of associated project ids
type: array
items:
type: string
tags:
description: List of associated tags
type: array
items:
type: string
userIdTypes:
description: >-
List of identifier columns in this table. For example, "id"
or "anonymous_id"
type: array
items:
type: string
userIdColumns:
description: >-
Maps an identifier type to the column holding it, for SQL
that does not alias its columns to the identifier type
names, e.g. `{"user_id": "userId"}`. May also be a
single-level field path into a JSON column
(`properties.userId`). Unmapped types use the identifier
type name as the column name.
type: object
propertyNames:
type: string
additionalProperties:
type: string
aggregatedFactTableSettings:
description: >-
Settings for maintaining shared daily aggregated tables (a
subset of userIdTypes plus the daily update time and restate
lookback window) used to speed up CUPED. Requires the data
pipeline (pipeline-mode) feature.
type: object
properties:
idTypes:
type: array
items:
type: string
updateTime:
type: object
properties:
time:
type: string
timezone:
type: string
required:
- time
- timezone
additionalProperties: false
lookbackWindow:
type: integer
exclusiveMinimum: 0
restateChunkDays:
type: integer
minimum: 1
maximum: 7
required:
- idTypes
- updateTime
- lookbackWindow
additionalProperties: false
sql:
description: The SQL query for this fact table
type: string
timestampColumn:
description: >-
The column holding the event timestamp. Must be a date
column on this fact table. Defaults to "timestamp" when
unset.
type: string
eventName:
description: The event name used in SQL template variables
type: string
columns:
description: >-
Optional array of columns to upsert by `column`: existing
columns are patched, new columns are created, and columns
not included are left unchanged. Omit `datatype` to leave an
existing column's type untouched; send "" to reset it for
auto-detection; new columns are auto-detected when
`datatype` is omitted or "". Slice-related properties
require an enterprise license.
type: array
items:
$ref: '#/components/schemas/FactTableColumnInput'
managedBy:
description: >-
Set this to "api" (or "dbt" for resources synced from dbt)
to disable editing in the GrowthBook UI
type: string
enum:
- ''
- api
- admin
- dbt
archived:
type: boolean
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
factTable:
$ref: '#/components/schemas/FactTable'
required:
- factTable
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/fact-tables/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"name":"New Fact Table Name"}'
delete:
operationId: deleteFactTable
summary: Deletes a single fact table
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
description: The ID of the deleted fact table
example: ftb_123abc
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE 'https://api.growthbook.io/api/v1/fact-tables/abc123'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/fact-tables/{factTableId}/filters:
get:
operationId: listFactTableFilters
summary: Get all filters for a fact table
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/factTableId'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
factTableFilters:
type: array
items:
$ref: '#/components/schemas/FactTableFilter'
required:
- factTableFilters
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/fact-tables/abc123/filters' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postFactTableFilter
summary: Create a single fact table filter
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/factTableId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name. Put details in `description`.
type: string
description:
description: Description of the fact table filter
type: string
maxLength: 10000
value:
description: The SQL expression for this filter.
example: country = 'US'
type: string
managedBy:
description: >-
Set this to "api" to disable editing in the GrowthBook UI.
Before you do this, the Fact Table itself must also be
marked as "api"
type: string
enum:
- ''
- api
required:
- name
- value
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
factTableFilter:
$ref: '#/components/schemas/FactTableFilter'
required:
- factTableFilter
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/fact-tables/abc123/filters' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"name":"High Value Order","value":"amount>100"}'
/v1/fact-tables/{factTableId}/filters/{id}:
get:
operationId: getFactTableFilter
summary: Get a single fact filter
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/factTableId'
- $ref: '#/components/parameters/id'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
factTableFilter:
$ref: '#/components/schemas/FactTableFilter'
required:
- factTableFilter
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/fact-tables/abc123/filters/abc123'
\
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: updateFactTableFilter
summary: Update a single fact table filter
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/factTableId'
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name. Put details in `description`.
type: string
description:
description: Description of the fact table filter
type: string
maxLength: 10000
value:
description: The SQL expression for this filter.
example: country = 'US'
type: string
managedBy:
description: >-
Set this to "api" to disable editing in the GrowthBook UI.
Before you do this, the Fact Table itself must also be
marked as "api"
type: string
enum:
- ''
- api
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
factTableFilter:
$ref: '#/components/schemas/FactTableFilter'
required:
- factTableFilter
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/fact-tables/abc123/filters/abc123'
\
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"value":"amount > 50"}'
delete:
operationId: deleteFactTableFilter
summary: Deletes a single fact table filter
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/factTableId'
- $ref: '#/components/parameters/id'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
description: The ID of the deleted fact filter
example: flt_123abc
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/fact-tables/abc123/filters/abc123'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/fact-tables/{factTableId}/virtual-columns:
post:
operationId: postFactTableVirtualColumn
summary: Create a virtual (computed) column on a fact table
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/factTableId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
column:
description: >-
The column identifier used in generated SQL. Must contain
only letters, numbers, and underscores and end with `_vc`.
example: revenue_vc
type: string
name:
description: Display name for the column
type: string
description:
description: Put context here, not in the name.
type: string
maxLength: 10000
numberFormat:
type: string
enum:
- ''
- currency
- time:seconds
- time:milliseconds
- memory:bytes
- memory:kilobytes
datatype:
description: The data type of the computed column
type: string
enum:
- number
- string
- date
- boolean
- json
- binary
- other
sql:
description: The SQL expression that computes the column value
example: price * quantity
type: string
required:
- column
- datatype
- sql
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
factTableColumn:
$ref: '#/components/schemas/FactTableColumn'
required:
- factTableColumn
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/fact-tables/abc123/virtual-columns'
\
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"column":"revenue_vc","datatype":"number","sql":"price * quantity"}'
/v1/fact-tables/{factTableId}/virtual-columns/{id}:
post:
operationId: updateFactTableVirtualColumn
summary: Update a virtual (computed) column on a fact table
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/factTableId'
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Display name for the column
type: string
description:
description: Put context here, not in the name.
type: string
maxLength: 10000
numberFormat:
type: string
enum:
- ''
- currency
- time:seconds
- time:milliseconds
- memory:bytes
- memory:kilobytes
datatype:
description: The data type of the computed column
type: string
enum:
- number
- string
- date
- boolean
- json
- binary
- other
sql:
description: The SQL expression that computes the column value
type: string
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
factTableColumn:
$ref: '#/components/schemas/FactTableColumn'
required:
- factTableColumn
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/fact-tables/abc123/virtual-columns/revenue_vc'
\
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"sql":"price * quantity * 1.1"}'
delete:
operationId: deleteFactTableVirtualColumn
summary: Delete a virtual (computed) column from a fact table
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/factTableId'
- $ref: '#/components/parameters/id'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
description: The id of the deleted virtual column
example: revenue_vc
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/fact-tables/abc123/virtual-columns/revenue_vc'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/fact-tables/{id}/aggregated-tables:
get:
operationId: getAggregatedFactTables
summary: >-
Get the materialization status of a fact table's shared daily aggregated
tables
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
aggregatedFactTables:
type: array
items:
$ref: '#/components/schemas/AggregatedFactTable'
nextScheduledUpdate:
description: >-
When the next scheduled nightly refresh will run, or null
if no schedule is configured
anyOf:
- format: date-time
type: string
- type: 'null'
required:
- aggregatedFactTables
- nextScheduledUpdate
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/fact-tables/abc123/aggregated-tables'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/fact-tables/{id}/aggregated-tables/refresh:
post:
operationId: refreshAggregatedFactTable
summary: >-
Force a refresh or full restate of a fact table's shared daily
aggregated tables
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
idType:
description: >-
Limit the refresh to a single id type. If omitted, all of
the fact table's aggregatedFactTableSettings.idTypes are
refreshed.
type: string
fullRestate:
description: >-
Drop and recreate the table, re-scanning the retained
window. This is significantly more expensive than the
default incremental append (it scans ~2-3 months of
history).
type: boolean
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
runs:
description: One entry per id type refreshed
type: array
items:
$ref: '#/components/schemas/AggregatedTableRefreshTrigger'
required:
- runs
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/fact-tables/abc123/aggregated-tables/refresh'
\
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"fullRestate":false}'
/v1/fact-tables/{id}/aggregated-tables/runs:
get:
operationId: listAggregatedTableRuns
summary: List aggregated table runs
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/idType'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
runs:
description: A list of the aggregated table runs for the fact table
type: array
items:
$ref: '#/components/schemas/AggregatedTableRunSummary'
required:
- runs
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/fact-tables/ftb_123/aggregated-tables/runs?idType=user_id'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/fact-tables/{id}/aggregated-tables/runs/{runId}:
get:
operationId: getAggregatedTableRun
summary: Get a single aggregated table run
tags:
- fact-tables
parameters:
- name: id
in: path
required: true
description: The id of the fact table
schema:
description: The id of the fact table
type: string
- $ref: '#/components/parameters/runId'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
run:
$ref: '#/components/schemas/AggregatedTableRun'
required:
- run
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/fact-tables/abc123/aggregated-tables/runs/aftr_abc123'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/fact-metrics:
get:
operationId: listFactMetrics
summary: Get all fact metrics
tags:
- fact-metrics
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/datasourceId'
- $ref: '#/components/parameters/projectId'
- name: factTableId
in: query
description: >-
Filter by Fact Table Id (for ratio metrics, only the numerator is
considered)
schema:
description: >-
Filter by Fact Table Id (for ratio metrics, only the numerator is
considered)
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
factMetrics:
type: array
items:
$ref: '#/components/schemas/FactMetric'
required:
- factMetrics
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/fact-metrics' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postFactMetric
summary: Create a single fact metric
tags:
- fact-metrics
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: >-
Short display name (e.g. `Purchases per user`). Put the
definition in `description`.
type: string
description:
description: Markdown. Put context here, not in the name.
type: string
maxLength: 10000
owner:
description: >-
The userId or email address of the owner. If an email
address is provided, it will be used to look up the userId
of the matching organization member. If an ID is provided,
it will be validated as existing in the organization.
type: string
projects:
type: array
items:
type: string
tags:
description: >-
Tags for filtering and grouping. Use these instead of
encoding groups in names.
type: array
items:
type: string
metricType:
type: string
enum:
- proportion
- retention
- mean
- quantile
- ratio
- dailyParticipation
- funnel
numerator:
anyOf:
- type: object
properties:
factTableId:
type: string
column:
description: >-
Must be empty for proportion metrics and
dailyParticipation metrics. Otherwise, the column
name or one of the special values: '$$distinctUsers'
or '$$count' (or '$$distinctDates' if metricType is
'mean' or 'ratio' or 'quantile' and
quantileSettings.type is 'unit')
type: string
aggregation:
description: >-
User aggregation of selected column. Either sum or
max for numeric columns; count distinct for string
columns; hll merge / kll merge for pre-built sketch
columns (requires data-source support); ignored for
special columns. Default: sum. If you specify a
string column you must explicitly specify count
distinct. Not used for proportion metrics; for event
quantile metrics only kll merge is applicable.
type: string
enum:
- sum
- max
- count distinct
- hll merge
- kll merge
filters:
deprecated: true
description: >-
Array of Fact Table Filter Ids. Deprecated, use
rowFilters instead.
type: array
items:
type: string
inlineFilters:
deprecated: true
description: >-
Inline filters to apply to the fact table. Keys are
column names, values are arrays of values to filter
by. Deprecated, use rowFilters instead.
type: object
propertyNames:
type: string
additionalProperties:
type: array
items:
type: string
rowFilters:
description: >-
Filters to apply to the rows of the fact table
before aggregation.
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- '>'
- <
- '>='
- <=
- between
- not_between
- in
- not_in
- is_null
- not_null
- is_true
- is_false
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- sql_expr
- saved_filter
values:
description: >-
Not required for is_null, not_null, is_true,
is_false operators. The between and
not_between operators take at most two values,
a lower and an upper bound in that order;
leave a bound as an empty string for an
open-ended range.
type: array
items:
type: string
column:
description: >-
Required for all operators except sql_expr and
saved_filter.
type: string
required:
- operator
additionalProperties: false
aggregateFilterColumn:
description: >-
Column to use to filter users after aggregation.
Either '$$count' of rows or the name of a numeric
column that will be summed by user. Must specify
`aggregateFilter` if using this. Only can be used
with 'retention' and 'proportion' metrics.
type: string
aggregateFilter:
description: >-
Simple comparison operator and value to apply after
aggregation (e.g. '= 10' or '>= 1'). Requires
`aggregateFilterColumn`.
type: string
required:
- factTableId
additionalProperties: false
- type: 'null'
denominator:
description: Only when metricType is 'ratio'
type: object
properties:
factTableId:
type: string
column:
description: >-
The column name or one of the special values:
'$$distinctUsers' or '$$count' (or '$$distinctDates' if
metricType is 'mean' or 'ratio' or 'quantile' and
quantileSettings.type is 'unit')
type: string
aggregation:
description: >-
User aggregation of selected column. Either sum or max
for numeric columns; count distinct for string columns;
hll merge / kll merge for pre-built sketch columns
(requires data-source support); ignored for special
columns. Default: sum. If you specify a string column
you must explicitly specify count distinct. Not used for
proportion metrics; for event quantile metrics only kll
merge is applicable.
type: string
enum:
- sum
- max
- count distinct
- hll merge
- kll merge
filters:
deprecated: true
description: >-
Array of Fact Table Filter Ids. Deprecated, use
rowFilters instead.
type: array
items:
type: string
inlineFilters:
deprecated: true
description: >-
Inline filters to apply to the fact table. Keys are
column names, values are arrays of values to filter by.
Deprecated, use rowFilters instead.
type: object
propertyNames:
type: string
additionalProperties:
type: array
items:
type: string
rowFilters:
description: >-
Filters to apply to the rows of the fact table before
aggregation.
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- '>'
- <
- '>='
- <=
- between
- not_between
- in
- not_in
- is_null
- not_null
- is_true
- is_false
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- sql_expr
- saved_filter
values:
description: >-
Not required for is_null, not_null, is_true,
is_false operators. The between and not_between
operators take at most two values, a lower and an
upper bound in that order; leave a bound as an
empty string for an open-ended range.
type: array
items:
type: string
column:
description: >-
Required for all operators except sql_expr and
saved_filter.
type: string
required:
- operator
additionalProperties: false
required:
- factTableId
- column
additionalProperties: false
inverse:
description: >-
Set to true for things like Bounce Rate, where you want the
metric to decrease
type: boolean
quantileSettings:
description: >-
Controls the settings for quantile metrics (mandatory if
metricType is "quantile")
type: object
properties:
type:
description: >-
Whether the quantile is over unit aggregations or raw
event values
type: string
enum:
- event
- unit
ignoreZeros:
description: >-
If true, zero values will be ignored when calculating
the quantile
type: boolean
quantile:
description: The quantile value (from 0.001 to 0.999)
type: number
minimum: 0.001
maximum: 0.999
multipleOf: 0.001
quantileEventCountColumn:
description: >-
Optional override for the source-column name used to
recover per-row event counts when numerator.aggregation
is 'kll merge'. Defaults to
'_n_events'. Only valid for
event-quantile metrics with a 'kll merge' numerator.
type: string
required:
- type
- ignoreZeros
- quantile
additionalProperties: false
funnelSettings:
description: >-
Funnel metric settings (required when metricType is
"funnel")
type: object
properties:
steps:
description: Ordered list of funnel steps. Minimum 2 steps required.
minItems: 2
maxItems: 20
type: array
items:
type: object
properties:
name:
description: Display name for the funnel step
type: string
factTableId:
description: The fact table this step draws events from
type: string
rowFilters:
description: >-
Filters that decide whether an event row counts as
this step
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- '>'
- <
- '>='
- <=
- between
- not_between
- in
- not_in
- is_null
- not_null
- is_true
- is_false
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- sql_expr
- saved_filter
values:
description: >-
Not required for is_null, not_null, is_true,
is_false operators. The between and
not_between operators take at most two
values, a lower and an upper bound in that
order; leave a bound as an empty string for
an open-ended range.
type: array
items:
type: string
column:
description: >-
Required for all operators except sql_expr
and saved_filter.
type: string
required:
- operator
additionalProperties: false
optional:
description: >-
When true, this step still counts for its own
conversion but does not anchor later steps. Later
steps window off the nearest prior required step
(or exposure, for experiment funnel metrics, when
every prior step is optional).
type: boolean
conversionWindow:
anyOf:
- description: >-
Bounds how long after the nearest prior
required step (or exposure, for the first step
/ after only-optional priors of an experiment
funnel metric) this step's event can occur.
type: object
properties:
unit:
type: string
enum:
- weeks
- days
- hours
- minutes
value:
type: number
exclusiveMinimum: 0
required:
- unit
- value
additionalProperties: false
- type: 'null'
required:
- name
- factTableId
- rowFilters
- optional
additionalProperties: false
ordering:
description: >-
Step ordering mode. Only 'sequential' is supported in
v1.
type: string
enum:
- sequential
concurrencyWindowSeconds:
description: >-
Out-of-order tolerance between adjacent steps in
seconds. Defaults to 0.
type: integer
minimum: 0
required:
- steps
additionalProperties: false
cappingSettings:
description: >-
Upper cap. Omit on update to preserve it. Use type: none to
disable it explicitly. Invalid values are rejected.
type: object
properties:
type:
type: string
enum:
- none
- absolute
- percentile
value:
description: >-
When type is absolute, this must be a finite number
greater than zero. When type is percentile, this must be
strictly between 0 and 1. Required when enabling capping
or changing type; omitted values are preserved only for
same-type updates.
type: number
ignoreZeros:
description: >-
If true and capping is `percentile`, zeros will be
ignored when calculating the percentile.
type: boolean
required:
- type
additionalProperties: false
lowerCappingSettings:
description: >-
Independent lower cap. Omit on update to preserve it. Use
null or type: none to disable it explicitly. Invalid values
are rejected. For mixed cap types, the absolute bound takes
precedence if thresholds cross.
anyOf:
- description: >-
Independent lower-tail capping settings. Configured
separately from the upper tail, so the type can differ.
type: object
properties:
type:
type: string
enum:
- none
- absolute
- percentile
value:
description: >-
When type is absolute, this is a finite lower bound,
including zero or negative values. When type is
percentile, this must be strictly between 0 and 1.
Required when enabling capping or changing type;
omitted values are preserved only for same-type
updates.
type: number
ignoreZeros:
description: >-
If true and capping is `percentile`, zeros will be
ignored when calculating the percentile.
type: boolean
required:
- type
additionalProperties: false
- type: 'null'
windowSettings:
description: Controls the conversion window for the metric
type: object
properties:
type:
type: string
enum:
- none
- conversion
- lookback
delayHours:
deprecated: true
description: >-
Wait this many hours after experiment exposure before
counting conversions. Ignored if delayValue is set.
type: number
delayValue:
description: >-
Wait this long after experiment exposure before counting
conversions.
type: number
delayUnit:
description: Default `hours`.
type: string
enum:
- minutes
- hours
- days
- weeks
windowValue:
type: number
windowUnit:
description: Default `hours`.
type: string
enum:
- minutes
- hours
- days
- weeks
required:
- type
additionalProperties: false
priorSettings:
description: >-
Controls the bayesian prior for the metric. If omitted,
organization defaults will be used.
type: object
properties:
override:
description: >-
If false, the organization default settings will be used
instead of the other settings in this object
type: boolean
proper:
description: >-
If true, the `mean` and `stddev` will be used, otherwise
we will use an improper flat prior.
type: boolean
mean:
description: >-
The mean of the prior distribution of relative effects
in proportion terms (e.g. 0.01 is 1%)
type: number
stddev:
description: >-
Must be > 0. The standard deviation of the prior
distribution of relative effects in proportion terms.
type: number
exclusiveMinimum: 0
required:
- override
- proper
- mean
- stddev
additionalProperties: false
regressionAdjustmentSettings:
description: >-
Controls the regression adjustment (CUPED) settings for the
metric
type: object
properties:
override:
description: If false, the organization default settings will be used
type: boolean
enabled:
description: >-
Controls whether or not regression adjustment is applied
to the metric
type: boolean
days:
description: >-
Number of pre-exposure days to use for the regression
adjustment
type: number
required:
- override
additionalProperties: false
riskThresholdSuccess:
deprecated: true
description: No longer used. Accepted and ignored.
type: number
riskThresholdDanger:
deprecated: true
description: No longer used. Accepted and ignored.
type: number
displayAsPercentage:
description: >-
If true and the metric is a ratio or dailyParticipation
metric, variation means will be displayed as a percentage.
Defaults to true for dailyParticipation metrics and false
for ratio metrics.
type: boolean
minPercentChange:
description: >-
Minimum percent change to consider uplift significant, as a
proportion (e.g. put 0.005 for 0.5%)
type: number
minimum: 0
maxPercentChange:
description: >-
Maximum percent change to consider uplift significant, as a
proportion (e.g. put 0.5 for 50%)
type: number
minimum: 0
minSampleSize:
type: number
minimum: 0
targetMDE:
description: >-
The percentage change that you want to reliably detect
before ending an experiment, as a proportion (e.g. put 0.1
for 10%). This is used to estimate the "Days Left" for
running experiments.
type: number
minimum: 0
managedBy:
description: >-
Set this to "api" (or "dbt" for resources synced from dbt)
to disable editing in the GrowthBook UI
type: string
enum:
- ''
- api
- admin
- dbt
metricAutoSlices:
description: >-
Array of slice column names that will be automatically
included in metric analysis. This is an enterprise feature.
type: array
items:
type: string
replaces:
description: >-
Ids of older metrics (legacy or fact) that this metric
supersedes, for example the legacy metric it was migrated
from. Cannot include this metric's own id. Informational
only - GrowthBook uses it to link the old and new
definitions in the UI and to keep showing results from a
snapshot that was created before an experiment switched to
this metric. This field can only be set through the API.
type: array
items:
type: string
required:
- name
- metricType
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
factMetric:
$ref: '#/components/schemas/FactMetric'
required:
- factMetric
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/fact-metrics' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"name":"Purchased","metricType":"proportion","numerator":{"factTableId":"ftb_abc123","column":"$$distinctUsers","filters":[]},"priorSettings":{"override":false,"proper":false,"mean":0,"stddev":0.3}}'
/v1/fact-metrics/{id}:
get:
operationId: getFactMetric
summary: Get a single fact metric
tags:
- fact-metrics
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
factMetric:
$ref: '#/components/schemas/FactMetric'
required:
- factMetric
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/fact-metrics/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: updateFactMetric
summary: Update a single fact metric
tags:
- fact-metrics
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: >-
Short display name (e.g. `Purchases per user`). Put the
definition in `description`.
type: string
description:
description: Markdown. Put context here, not in the name.
type: string
maxLength: 10000
owner:
description: >-
The userId or email address of the owner. If an email
address is provided, it will be used to look up the userId
of the matching organization member. If an ID is provided,
it will be validated as existing in the organization.
type: string
projects:
type: array
items:
type: string
tags:
description: >-
Tags for filtering and grouping. Use these instead of
encoding groups in names.
type: array
items:
type: string
metricType:
type: string
enum:
- proportion
- retention
- mean
- quantile
- ratio
- dailyParticipation
- funnel
numerator:
anyOf:
- type: object
properties:
factTableId:
type: string
column:
description: >-
Must be empty for proportion metrics and
dailyParticipation metrics. Otherwise, the column
name or one of the special values: '$$distinctUsers'
or '$$count' (or '$$distinctDates' if metricType is
'mean' or 'ratio' or 'quantile' and
quantileSettings.type is 'unit')
type: string
aggregation:
description: >-
User aggregation of selected column. Either sum or
max for numeric columns; count distinct for string
columns; hll merge / kll merge for pre-built sketch
columns (requires data-source support); ignored for
special columns. Default: sum. If you specify a
string column you must explicitly specify count
distinct. Not used for proportion metrics; for event
quantile metrics only kll merge is applicable.
type: string
enum:
- sum
- max
- count distinct
- hll merge
- kll merge
filters:
deprecated: true
description: >-
Array of Fact Table Filter Ids. Deprecated, use
rowFilters instead.
type: array
items:
type: string
inlineFilters:
deprecated: true
description: >-
Inline filters to apply to the fact table. Keys are
column names, values are arrays of values to filter
by. Deprecated, use rowFilters instead.
type: object
propertyNames:
type: string
additionalProperties:
type: array
items:
type: string
rowFilters:
description: >-
Filters to apply to the rows of the fact table
before aggregation.
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- '>'
- <
- '>='
- <=
- between
- not_between
- in
- not_in
- is_null
- not_null
- is_true
- is_false
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- sql_expr
- saved_filter
values:
description: >-
Not required for is_null, not_null, is_true,
is_false operators. The between and
not_between operators take at most two values,
a lower and an upper bound in that order;
leave a bound as an empty string for an
open-ended range.
type: array
items:
type: string
column:
description: >-
Required for all operators except sql_expr and
saved_filter.
type: string
required:
- operator
additionalProperties: false
aggregateFilterColumn:
description: >-
Column to use to filter users after aggregation.
Either '$$count' of rows or the name of a numeric
column that will be summed by user. Must specify
`aggregateFilter` if using this. Only can be used
with 'retention' and 'proportion' metrics.
type: string
aggregateFilter:
description: >-
Simple comparison operator and value to apply after
aggregation (e.g. '= 10' or '>= 1'). Requires
`aggregateFilterColumn`.
type: string
required:
- factTableId
additionalProperties: false
- type: 'null'
denominator:
description: Only when metricType is 'ratio'
type: object
properties:
factTableId:
type: string
column:
description: >-
The column name or one of the special values:
'$$distinctUsers' or '$$count' (or '$$distinctDates' if
metricType is 'mean' or 'ratio' or 'quantile' and
quantileSettings.type is 'unit')
type: string
aggregation:
description: >-
User aggregation of selected column. Either sum or max
for numeric columns; count distinct for string columns;
hll merge / kll merge for pre-built sketch columns
(requires data-source support); ignored for special
columns. Default: sum. If you specify a string column
you must explicitly specify count distinct. Not used for
proportion metrics; for event quantile metrics only kll
merge is applicable.
type: string
enum:
- sum
- max
- count distinct
- hll merge
- kll merge
filters:
deprecated: true
description: >-
Array of Fact Table Filter Ids. Deprecated, use
rowFilters instead.
type: array
items:
type: string
inlineFilters:
deprecated: true
description: >-
Inline filters to apply to the fact table. Keys are
column names, values are arrays of values to filter by.
Deprecated, use rowFilters instead.
type: object
propertyNames:
type: string
additionalProperties:
type: array
items:
type: string
rowFilters:
description: >-
Filters to apply to the rows of the fact table before
aggregation.
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- '>'
- <
- '>='
- <=
- between
- not_between
- in
- not_in
- is_null
- not_null
- is_true
- is_false
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- sql_expr
- saved_filter
values:
description: >-
Not required for is_null, not_null, is_true,
is_false operators. The between and not_between
operators take at most two values, a lower and an
upper bound in that order; leave a bound as an
empty string for an open-ended range.
type: array
items:
type: string
column:
description: >-
Required for all operators except sql_expr and
saved_filter.
type: string
required:
- operator
additionalProperties: false
required:
- factTableId
- column
additionalProperties: false
inverse:
description: >-
Set to true for things like Bounce Rate, where you want the
metric to decrease
type: boolean
quantileSettings:
description: >-
Controls the settings for quantile metrics (mandatory if
metricType is "quantile")
type: object
properties:
type:
description: >-
Whether the quantile is over unit aggregations or raw
event values
type: string
enum:
- event
- unit
ignoreZeros:
description: >-
If true, zero values will be ignored when calculating
the quantile
type: boolean
quantile:
description: The quantile value (from 0.001 to 0.999)
type: number
minimum: 0.001
maximum: 0.999
multipleOf: 0.001
quantileEventCountColumn:
description: >-
Optional override for the source-column name used to
recover per-row event counts when numerator.aggregation
is 'kll merge'. Defaults to
'_n_events'. Only valid for
event-quantile metrics with a 'kll merge' numerator.
type: string
required:
- type
- ignoreZeros
- quantile
additionalProperties: false
funnelSettings:
description: >-
Funnel metric settings (required when metricType is
"funnel")
type: object
properties:
steps:
description: Ordered list of funnel steps. Minimum 2 steps required.
minItems: 2
maxItems: 20
type: array
items:
type: object
properties:
name:
description: Display name for the funnel step
type: string
factTableId:
description: The fact table this step draws events from
type: string
rowFilters:
description: >-
Filters that decide whether an event row counts as
this step
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- '>'
- <
- '>='
- <=
- between
- not_between
- in
- not_in
- is_null
- not_null
- is_true
- is_false
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- sql_expr
- saved_filter
values:
description: >-
Not required for is_null, not_null, is_true,
is_false operators. The between and
not_between operators take at most two
values, a lower and an upper bound in that
order; leave a bound as an empty string for
an open-ended range.
type: array
items:
type: string
column:
description: >-
Required for all operators except sql_expr
and saved_filter.
type: string
required:
- operator
additionalProperties: false
optional:
description: >-
When true, this step still counts for its own
conversion but does not anchor later steps. Later
steps window off the nearest prior required step
(or exposure, for experiment funnel metrics, when
every prior step is optional).
type: boolean
conversionWindow:
anyOf:
- description: >-
Bounds how long after the nearest prior
required step (or exposure, for the first step
/ after only-optional priors of an experiment
funnel metric) this step's event can occur.
type: object
properties:
unit:
type: string
enum:
- weeks
- days
- hours
- minutes
value:
type: number
exclusiveMinimum: 0
required:
- unit
- value
additionalProperties: false
- type: 'null'
required:
- name
- factTableId
- rowFilters
- optional
additionalProperties: false
ordering:
description: >-
Step ordering mode. Only 'sequential' is supported in
v1.
type: string
enum:
- sequential
concurrencyWindowSeconds:
description: >-
Out-of-order tolerance between adjacent steps in
seconds. Defaults to 0.
type: integer
minimum: 0
required:
- steps
additionalProperties: false
cappingSettings:
description: >-
Upper cap. Omit on update to preserve it. Use type: none to
disable it explicitly. Invalid values are rejected.
type: object
properties:
type:
type: string
enum:
- none
- absolute
- percentile
value:
description: >-
When type is absolute, this must be a finite number
greater than zero. When type is percentile, this must be
strictly between 0 and 1. Required when enabling capping
or changing type; omitted values are preserved only for
same-type updates.
type: number
ignoreZeros:
description: >-
If true and capping is `percentile`, zeros will be
ignored when calculating the percentile.
type: boolean
required:
- type
additionalProperties: false
lowerCappingSettings:
description: >-
Independent lower cap. Omit on update to preserve it. Use
null or type: none to disable it explicitly. Invalid values
are rejected. For mixed cap types, the absolute bound takes
precedence if thresholds cross.
anyOf:
- description: >-
Independent lower-tail capping settings. Configured
separately from the upper tail, so the type can differ.
type: object
properties:
type:
type: string
enum:
- none
- absolute
- percentile
value:
description: >-
When type is absolute, this is a finite lower bound,
including zero or negative values. When type is
percentile, this must be strictly between 0 and 1.
Required when enabling capping or changing type;
omitted values are preserved only for same-type
updates.
type: number
ignoreZeros:
description: >-
If true and capping is `percentile`, zeros will be
ignored when calculating the percentile.
type: boolean
required:
- type
additionalProperties: false
- type: 'null'
windowSettings:
description: Controls the conversion window for the metric
type: object
properties:
type:
type: string
enum:
- none
- conversion
- lookback
delayHours:
deprecated: true
description: >-
Wait this many hours after experiment exposure before
counting conversions. Ignored if delayValue is set.
type: number
delayValue:
description: >-
Wait this long after experiment exposure before counting
conversions.
type: number
delayUnit:
description: Default `hours`.
type: string
enum:
- minutes
- hours
- days
- weeks
windowValue:
type: number
windowUnit:
description: Default `hours`.
type: string
enum:
- minutes
- hours
- days
- weeks
required:
- type
additionalProperties: false
priorSettings:
description: >-
Controls the bayesian prior for the metric. If omitted,
organization defaults will be used.
type: object
properties:
override:
description: >-
If false, the organization default settings will be used
instead of the other settings in this object
type: boolean
proper:
description: >-
If true, the `mean` and `stddev` will be used, otherwise
we will use an improper flat prior.
type: boolean
mean:
description: >-
The mean of the prior distribution of relative effects
in proportion terms (e.g. 0.01 is 1%)
type: number
stddev:
description: >-
Must be > 0. The standard deviation of the prior
distribution of relative effects in proportion terms.
type: number
exclusiveMinimum: 0
required:
- override
- proper
- mean
- stddev
additionalProperties: false
regressionAdjustmentSettings:
description: >-
Controls the regression adjustment (CUPED) settings for the
metric
type: object
properties:
override:
description: If false, the organization default settings will be used
type: boolean
enabled:
description: >-
Controls whether or not regression adjustment is applied
to the metric
type: boolean
days:
description: >-
Number of pre-exposure days to use for the regression
adjustment
type: number
required:
- override
additionalProperties: false
riskThresholdSuccess:
deprecated: true
description: No longer used. Accepted and ignored.
type: number
riskThresholdDanger:
deprecated: true
description: No longer used. Accepted and ignored.
type: number
displayAsPercentage:
description: >-
If true and the metric is a ratio or dailyParticipation
metric, variation means will be displayed as a percentage.
Defaults to true for dailyParticipation metrics and false
for ratio metrics.
type: boolean
minPercentChange:
description: >-
Minimum percent change to consider uplift significant, as a
proportion (e.g. put 0.005 for 0.5%)
type: number
minimum: 0
maxPercentChange:
description: >-
Maximum percent change to consider uplift significant, as a
proportion (e.g. put 0.5 for 50%)
type: number
minimum: 0
minSampleSize:
type: number
minimum: 0
targetMDE:
description: >-
The percentage change that you want to reliably detect
before ending an experiment, as a proportion (e.g. put 0.1
for 10%). This is used to estimate the "Days Left" for
running experiments.
type: number
minimum: 0
managedBy:
description: >-
Set this to "api" (or "dbt" for resources synced from dbt)
to disable editing in the GrowthBook UI
type: string
enum:
- ''
- api
- admin
- dbt
metricAutoSlices:
description: >-
Array of slice column names that will be automatically
included in metric analysis. This is an enterprise feature.
type: array
items:
type: string
replaces:
description: >-
Ids of older metrics (legacy or fact) that this metric
supersedes, for example the legacy metric it was migrated
from. Cannot include this metric's own id. Informational
only - GrowthBook uses it to link the old and new
definitions in the UI and to keep showing results from a
snapshot that was created before an experiment switched to
this metric. This field can only be set through the API.
type: array
items:
type: string
archived:
description: >-
Set to true to archive the metric. Archived metrics are
hidden by default in the UI and excluded from new
experiments.
type: boolean
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
factMetric:
$ref: '#/components/schemas/FactMetric'
required:
- factMetric
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST 'https://api.growthbook.io/api/v1/fact-metrics/abc123'
\
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"name":"Updated Metric Name"}'
delete:
operationId: deleteFactMetric
summary: Deletes a single fact metric
tags:
- fact-metrics
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
description: The ID of the deleted fact metric
example: fact__123abc
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/fact-metrics/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/fact-metrics/{id}/analysis:
post:
operationId: postFactMetricAnalysis
summary: Create a fact metric analysis
tags:
- fact-metrics
parameters:
- name: id
in: path
required: true
description: The fact metric id to analyze
schema:
description: The fact metric id to analyze
type: string
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
userIdType:
description: >-
The identifier type to use for the analysis. If not
provided, defaults to the first available identifier type in
the fact table.
type: string
lookbackDays:
description: >-
Number of days to look back for the analysis. Defaults to
30.
type: number
minimum: 1
maximum: 999999
populationType:
description: >-
The type of population to analyze. Defaults to 'factTable',
meaning the analysis will return the metric value for all
units found in the fact table.
type: string
enum:
- factTable
- segment
populationId:
description: >-
The ID of the population (e.g., segment ID) when
populationType is not 'factTable'. Defaults to null.
anyOf:
- type: string
- type: 'null'
additionalNumeratorFilters:
description: >-
We support passing in adhoc filters for an analysis that
don't live on the metric itself. These are in addition to
the metric's filters. To use this, you can pass in an array
of Fact Table Filter Ids.
type: array
items:
type: string
additionalDenominatorFilters:
description: >-
We support passing in adhoc filters for an analysis that
don't live on the metric itself. These are in addition to
the metric's filters. To use this, you can pass in an array
of Fact Table Filter Ids.
type: array
items:
type: string
useCache:
description: >-
Whether to use a cached query if one exists. Defaults to
true.
type: boolean
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
metricAnalysis:
$ref: '#/components/schemas/MetricAnalysis'
required:
- metricAnalysis
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/fact-metrics/{id}/analysis' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"lookbackDays":90}'
/v1/bulk-import/facts:
post:
operationId: postBulkImportFacts
summary: Bulk import fact tables, filters, and metrics
description: >-
Creates or updates Fact Tables, Fact Table filters, and Fact Metrics.
Resources upsert by `id`. Pass `dryRun: true` to validate with zero
writes. Not transactional: a live mid-loop failure returns HTTP 400 (403
for a permission failure) with write counts and `errors`.
tags:
- fact-tables
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
defaultManagedBy:
description: >-
Fallback `managedBy` for Fact Tables and Fact Metrics that
omit the field. Defaults to `"api"`; the dbt sync sends
`"dbt"`. Filters inherit `"api"` only when the parent Fact
Table is api-managed.
type: string
enum:
- ''
- api
- admin
- dbt
dryRun:
description: Validate with zero writes.
type: boolean
factTables:
type: array
items:
type: object
properties:
id:
type: string
data:
type: object
properties:
name:
description: Short display name. Put details in `description`.
type: string
description:
description: Markdown. Put context here, not in the name.
type: string
maxLength: 10000
owner:
description: >-
The userId or email address of the owner. If an
email address is provided, it will be used to look
up the userId of the matching organization member.
If an ID is provided, it will be validated as
existing in the organization.
type: string
projects:
description: List of associated project ids
type: array
items:
type: string
tags:
description: List of associated tags
type: array
items:
type: string
datasource:
description: The datasource id
type: string
userIdTypes:
description: >-
List of identifier columns in this table. For
example, "id" or "anonymous_id"
type: array
items:
type: string
userIdColumns:
description: >-
Maps an identifier type to the column holding it,
for SQL that does not alias its columns to the
identifier type names, e.g. `{"user_id":
"userId"}`. May also be a single-level field path
into a JSON column (`properties.userId`). Unmapped
types use the identifier type name as the column
name.
type: object
propertyNames:
type: string
additionalProperties:
type: string
aggregatedFactTableSettings:
description: >-
Settings for maintaining shared daily aggregated
tables (a subset of userIdTypes plus the daily
update time and restate lookback window) used to
speed up CUPED. Requires the data pipeline
(pipeline-mode) feature.
type: object
properties:
idTypes:
type: array
items:
type: string
updateTime:
type: object
properties:
time:
type: string
timezone:
type: string
required:
- time
- timezone
additionalProperties: false
lookbackWindow:
type: integer
exclusiveMinimum: 0
restateChunkDays:
type: integer
minimum: 1
maximum: 7
required:
- idTypes
- updateTime
- lookbackWindow
additionalProperties: false
sql:
description: The SQL query for this fact table
type: string
timestampColumn:
description: >-
The column holding the event timestamp. Must be a
date column on this fact table. Defaults to
"timestamp" when unset.
type: string
eventName:
description: The event name used in SQL template variables
type: string
columns:
description: >-
Optional array of column definitions for this fact
table. On create, columns are stored as-is. On
update, columns upsert by `column`: existing
columns are patched, new columns are created, and
columns not included are left unchanged. Omit
`datatype` to leave an existing column's type
untouched; send "" to reset it for auto-detection;
new columns are auto-detected when `datatype` is
omitted or "". Datatype-dependent properties (e.g.
`alwaysInlineFilter`) are validated once the
datatype is known. Slice-related properties
require an enterprise license.
type: array
items:
$ref: '#/components/schemas/FactTableColumnInput'
managedBy:
description: >-
Set this to "api" (or "dbt" for resources synced
from dbt) to disable editing in the GrowthBook UI
type: string
enum:
- ''
- api
- admin
- dbt
required:
- name
- datasource
- userIdTypes
- sql
additionalProperties: false
required:
- id
- data
additionalProperties: false
factTableFilters:
type: array
items:
type: object
properties:
factTableId:
type: string
id:
type: string
data:
type: object
properties:
name:
description: Short display name. Put details in `description`.
type: string
description:
description: Description of the fact table filter
type: string
maxLength: 10000
value:
description: The SQL expression for this filter.
example: country = 'US'
type: string
managedBy:
description: >-
Set this to "api" to disable editing in the
GrowthBook UI. Before you do this, the Fact Table
itself must also be marked as "api"
type: string
enum:
- ''
- api
required:
- name
- value
additionalProperties: false
required:
- factTableId
- id
- data
additionalProperties: false
factMetrics:
type: array
items:
type: object
properties:
id:
type: string
data:
type: object
properties:
name:
description: >-
Short display name (e.g. `Purchases per user`).
Put the definition in `description`.
type: string
description:
description: Markdown. Put context here, not in the name.
type: string
maxLength: 10000
owner:
description: >-
The userId or email address of the owner. If an
email address is provided, it will be used to look
up the userId of the matching organization member.
If an ID is provided, it will be validated as
existing in the organization.
type: string
projects:
type: array
items:
type: string
tags:
description: >-
Tags for filtering and grouping. Use these instead
of encoding groups in names.
type: array
items:
type: string
metricType:
type: string
enum:
- proportion
- retention
- mean
- quantile
- ratio
- dailyParticipation
- funnel
numerator:
anyOf:
- type: object
properties:
factTableId:
type: string
column:
description: >-
Must be empty for proportion metrics and
dailyParticipation metrics. Otherwise, the
column name or one of the special values:
'$$distinctUsers' or '$$count' (or
'$$distinctDates' if metricType is 'mean'
or 'ratio' or 'quantile' and
quantileSettings.type is 'unit')
type: string
aggregation:
description: >-
User aggregation of selected column.
Either sum or max for numeric columns;
count distinct for string columns; hll
merge / kll merge for pre-built sketch
columns (requires data-source support);
ignored for special columns. Default: sum.
If you specify a string column you must
explicitly specify count distinct. Not
used for proportion metrics; for event
quantile metrics only kll merge is
applicable.
type: string
enum:
- sum
- max
- count distinct
- hll merge
- kll merge
filters:
deprecated: true
description: >-
Array of Fact Table Filter Ids.
Deprecated, use rowFilters instead.
type: array
items:
type: string
inlineFilters:
deprecated: true
description: >-
Inline filters to apply to the fact table.
Keys are column names, values are arrays
of values to filter by. Deprecated, use
rowFilters instead.
type: object
propertyNames:
type: string
additionalProperties:
type: array
items:
type: string
rowFilters:
description: >-
Filters to apply to the rows of the fact
table before aggregation.
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- '>'
- <
- '>='
- <=
- between
- not_between
- in
- not_in
- is_null
- not_null
- is_true
- is_false
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- sql_expr
- saved_filter
values:
description: >-
Not required for is_null, not_null,
is_true, is_false operators. The between
and not_between operators take at most
two values, a lower and an upper bound
in that order; leave a bound as an empty
string for an open-ended range.
type: array
items:
type: string
column:
description: >-
Required for all operators except
sql_expr and saved_filter.
type: string
required:
- operator
additionalProperties: false
aggregateFilterColumn:
description: >-
Column to use to filter users after
aggregation. Either '$$count' of rows or
the name of a numeric column that will be
summed by user. Must specify
`aggregateFilter` if using this. Only can
be used with 'retention' and 'proportion'
metrics.
type: string
aggregateFilter:
description: >-
Simple comparison operator and value to
apply after aggregation (e.g. '= 10' or
'>= 1'). Requires `aggregateFilterColumn`.
type: string
required:
- factTableId
additionalProperties: false
- type: 'null'
denominator:
description: Only when metricType is 'ratio'
type: object
properties:
factTableId:
type: string
column:
description: >-
The column name or one of the special values:
'$$distinctUsers' or '$$count' (or
'$$distinctDates' if metricType is 'mean' or
'ratio' or 'quantile' and
quantileSettings.type is 'unit')
type: string
aggregation:
description: >-
User aggregation of selected column. Either
sum or max for numeric columns; count distinct
for string columns; hll merge / kll merge for
pre-built sketch columns (requires data-source
support); ignored for special columns.
Default: sum. If you specify a string column
you must explicitly specify count distinct.
Not used for proportion metrics; for event
quantile metrics only kll merge is applicable.
type: string
enum:
- sum
- max
- count distinct
- hll merge
- kll merge
filters:
deprecated: true
description: >-
Array of Fact Table Filter Ids. Deprecated,
use rowFilters instead.
type: array
items:
type: string
inlineFilters:
deprecated: true
description: >-
Inline filters to apply to the fact table.
Keys are column names, values are arrays of
values to filter by. Deprecated, use
rowFilters instead.
type: object
propertyNames:
type: string
additionalProperties:
type: array
items:
type: string
rowFilters:
description: >-
Filters to apply to the rows of the fact table
before aggregation.
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- '>'
- <
- '>='
- <=
- between
- not_between
- in
- not_in
- is_null
- not_null
- is_true
- is_false
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- sql_expr
- saved_filter
values:
description: >-
Not required for is_null, not_null,
is_true, is_false operators. The between
and not_between operators take at most
two values, a lower and an upper bound
in that order; leave a bound as an empty
string for an open-ended range.
type: array
items:
type: string
column:
description: >-
Required for all operators except
sql_expr and saved_filter.
type: string
required:
- operator
additionalProperties: false
required:
- factTableId
- column
additionalProperties: false
inverse:
description: >-
Set to true for things like Bounce Rate, where you
want the metric to decrease
type: boolean
quantileSettings:
description: >-
Controls the settings for quantile metrics
(mandatory if metricType is "quantile")
type: object
properties:
type:
description: >-
Whether the quantile is over unit aggregations
or raw event values
type: string
enum:
- event
- unit
ignoreZeros:
description: >-
If true, zero values will be ignored when
calculating the quantile
type: boolean
quantile:
description: The quantile value (from 0.001 to 0.999)
type: number
minimum: 0.001
maximum: 0.999
multipleOf: 0.001
quantileEventCountColumn:
description: >-
Optional override for the source-column name
used to recover per-row event counts when
numerator.aggregation is 'kll merge'. Defaults
to '_n_events'. Only valid
for event-quantile metrics with a 'kll merge'
numerator.
type: string
required:
- type
- ignoreZeros
- quantile
additionalProperties: false
funnelSettings:
description: >-
Funnel metric settings (required when metricType
is "funnel")
type: object
properties:
steps:
description: >-
Ordered list of funnel steps. Minimum 2 steps
required.
minItems: 2
maxItems: 20
type: array
items:
type: object
properties:
name:
description: Display name for the funnel step
type: string
factTableId:
description: >-
The fact table this step draws events
from
type: string
rowFilters:
description: >-
Filters that decide whether an event row
counts as this step
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- '>'
- <
- '>='
- <=
- between
- not_between
- in
- not_in
- is_null
- not_null
- is_true
- is_false
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- sql_expr
- saved_filter
values:
description: >-
Not required for is_null, not_null,
is_true, is_false operators. The between
and not_between operators take at most
two values, a lower and an upper bound
in that order; leave a bound as an empty
string for an open-ended range.
type: array
items:
type: string
column:
description: >-
Required for all operators except
sql_expr and saved_filter.
type: string
required:
- operator
additionalProperties: false
optional:
description: >-
When true, this step still counts for
its own conversion but does not anchor
later steps. Later steps window off the
nearest prior required step (or
exposure, for experiment funnel metrics,
when every prior step is optional).
type: boolean
conversionWindow:
anyOf:
- description: >-
Bounds how long after the nearest prior
required step (or exposure, for the
first step / after only-optional priors
of an experiment funnel metric) this
step's event can occur.
type: object
properties:
unit:
type: string
enum:
- weeks
- days
- hours
- minutes
value:
type: number
exclusiveMinimum: 0
required:
- unit
- value
additionalProperties: false
- type: 'null'
required:
- name
- factTableId
- rowFilters
- optional
additionalProperties: false
ordering:
description: >-
Step ordering mode. Only 'sequential' is
supported in v1.
type: string
enum:
- sequential
concurrencyWindowSeconds:
description: >-
Out-of-order tolerance between adjacent steps
in seconds. Defaults to 0.
type: integer
minimum: 0
required:
- steps
additionalProperties: false
cappingSettings:
description: >-
Upper cap. Omit on update to preserve it. Use
type: none to disable it explicitly. Invalid
values are rejected.
type: object
properties:
type:
type: string
enum:
- none
- absolute
- percentile
value:
description: >-
When type is absolute, this must be a finite
number greater than zero. When type is
percentile, this must be strictly between 0
and 1. Required when enabling capping or
changing type; omitted values are preserved
only for same-type updates.
type: number
ignoreZeros:
description: >-
If true and capping is `percentile`, zeros
will be ignored when calculating the
percentile.
type: boolean
required:
- type
additionalProperties: false
lowerCappingSettings:
description: >-
Independent lower cap. Omit on update to preserve
it. Use null or type: none to disable it
explicitly. Invalid values are rejected. For mixed
cap types, the absolute bound takes precedence if
thresholds cross.
anyOf:
- description: >-
Independent lower-tail capping settings.
Configured separately from the upper tail, so
the type can differ.
type: object
properties:
type:
type: string
enum:
- none
- absolute
- percentile
value:
description: >-
When type is absolute, this is a finite
lower bound, including zero or negative
values. When type is percentile, this must
be strictly between 0 and 1. Required when
enabling capping or changing type; omitted
values are preserved only for same-type
updates.
type: number
ignoreZeros:
description: >-
If true and capping is `percentile`, zeros
will be ignored when calculating the
percentile.
type: boolean
required:
- type
additionalProperties: false
- type: 'null'
windowSettings:
description: Controls the conversion window for the metric
type: object
properties:
type:
type: string
enum:
- none
- conversion
- lookback
delayHours:
deprecated: true
description: >-
Wait this many hours after experiment exposure
before counting conversions. Ignored if
delayValue is set.
type: number
delayValue:
description: >-
Wait this long after experiment exposure
before counting conversions.
type: number
delayUnit:
description: Default `hours`.
type: string
enum:
- minutes
- hours
- days
- weeks
windowValue:
type: number
windowUnit:
description: Default `hours`.
type: string
enum:
- minutes
- hours
- days
- weeks
required:
- type
additionalProperties: false
priorSettings:
description: >-
Controls the bayesian prior for the metric. If
omitted, organization defaults will be used.
type: object
properties:
override:
description: >-
If false, the organization default settings
will be used instead of the other settings in
this object
type: boolean
proper:
description: >-
If true, the `mean` and `stddev` will be used,
otherwise we will use an improper flat prior.
type: boolean
mean:
description: >-
The mean of the prior distribution of relative
effects in proportion terms (e.g. 0.01 is 1%)
type: number
stddev:
description: >-
Must be > 0. The standard deviation of the
prior distribution of relative effects in
proportion terms.
type: number
exclusiveMinimum: 0
required:
- override
- proper
- mean
- stddev
additionalProperties: false
regressionAdjustmentSettings:
description: >-
Controls the regression adjustment (CUPED)
settings for the metric
type: object
properties:
override:
description: >-
If false, the organization default settings
will be used
type: boolean
enabled:
description: >-
Controls whether or not regression adjustment
is applied to the metric
type: boolean
days:
description: >-
Number of pre-exposure days to use for the
regression adjustment
type: number
required:
- override
additionalProperties: false
riskThresholdSuccess:
deprecated: true
description: No longer used. Accepted and ignored.
type: number
riskThresholdDanger:
deprecated: true
description: No longer used. Accepted and ignored.
type: number
displayAsPercentage:
description: >-
If true and the metric is a ratio or
dailyParticipation metric, variation means will be
displayed as a percentage. Defaults to true for
dailyParticipation metrics and false for ratio
metrics.
type: boolean
minPercentChange:
description: >-
Minimum percent change to consider uplift
significant, as a proportion (e.g. put 0.005 for
0.5%)
type: number
minimum: 0
maxPercentChange:
description: >-
Maximum percent change to consider uplift
significant, as a proportion (e.g. put 0.5 for
50%)
type: number
minimum: 0
minSampleSize:
type: number
minimum: 0
targetMDE:
description: >-
The percentage change that you want to reliably
detect before ending an experiment, as a
proportion (e.g. put 0.1 for 10%). This is used to
estimate the "Days Left" for running experiments.
type: number
minimum: 0
managedBy:
description: >-
Set this to "api" (or "dbt" for resources synced
from dbt) to disable editing in the GrowthBook UI
type: string
enum:
- ''
- api
- admin
- dbt
metricAutoSlices:
description: >-
Array of slice column names that will be
automatically included in metric analysis. This is
an enterprise feature.
type: array
items:
type: string
replaces:
description: >-
Ids of older metrics (legacy or fact) that this
metric supersedes, for example the legacy metric
it was migrated from. Cannot include this metric's
own id. Informational only - GrowthBook uses it to
link the old and new definitions in the UI and to
keep showing results from a snapshot that was
created before an experiment switched to this
metric. This field can only be set through the
API.
type: array
items:
type: string
archived:
description: >-
Set to true to archive the metric. Archived
metrics are hidden by default in the UI and
excluded from new experiments.
type: boolean
required:
- name
- metricType
additionalProperties: false
required:
- id
- data
additionalProperties: false
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
dryRun:
type: boolean
factTablesAdded:
type: integer
factTablesUpdated:
type: integer
factTableFiltersAdded:
type: integer
factTableFiltersUpdated:
type: integer
factMetricsAdded:
type: integer
factMetricsUpdated:
type: integer
errors:
type: array
items:
$ref: '#/components/schemas/BulkImportError'
required:
- success
- dryRun
- factTablesAdded
- factTablesUpdated
- factTableFiltersAdded
- factTableFiltersUpdated
- factMetricsAdded
- factMetricsUpdated
- errors
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/bulk-import/facts' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"factTables":[],"factTableFilters":[],"factMetrics":[]}'
/v1/code-refs:
post:
operationId: postCodeRefs
summary: Submit list of code references
tags:
- code-references
parameters:
- $ref: '#/components/parameters/deleteMissing'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
branch:
type: string
repoName:
type: string
refs:
type: array
items:
type: object
properties:
filePath:
type: string
startingLineNumber:
type: integer
lines:
type: string
flagKey:
type: string
contentHash:
type: string
required:
- filePath
- startingLineNumber
- lines
- flagKey
- contentHash
additionalProperties: false
required:
- branch
- repoName
- refs
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
featuresUpdated:
type: array
items:
type: string
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/code-refs' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"branch":"main","repoName":"my-repo","refs":[{"filePath":"src/app.ts","startingLineNumber":16,"lines":"...","flagKey":"my-feature","contentHash":"abc123"}]}'
get:
operationId: listCodeRefs
summary: Get list of all code references for the current organization
tags:
- code-references
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
codeRefs:
type: array
items:
$ref: '#/components/schemas/CodeRef'
required:
- codeRefs
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/code-refs' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/code-refs/{id}:
get:
operationId: getCodeRefs
summary: Get list of code references for a single feature id
tags:
- code-references
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
codeRefs:
type: array
items:
$ref: '#/components/schemas/CodeRef'
required:
- codeRefs
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/code-refs/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/members:
get:
operationId: listMembers
summary: Get all organization members
tags:
- members
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/userName'
- $ref: '#/components/parameters/userEmail'
- $ref: '#/components/parameters/globalRole'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
members:
type: array
items:
$ref: '#/components/schemas/Member'
required:
- members
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/members' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/members/{id}/role:
post:
operationId: updateMemberRole
summary: Update a member's role
description: >-
Update a member's global role (including any environment restrictions,
if applicable). Can also update a member's project roles if your plan
supports it.
tags:
- members
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
member:
type: object
properties:
role:
type: string
environments:
type: array
items:
type: string
additionalRoles:
description: >-
Additional roles granted alongside this one, in the same
scope. Each is granted independently and environment
access is the union across them.
type: array
items:
type: object
properties:
role:
type: string
environments:
type: array
items:
type: string
limitAccessByEnvironment:
type: boolean
required:
- role
- environments
additionalProperties: false
projectRoles:
type: array
items:
type: object
properties:
project:
type: string
role:
type: string
environments:
type: array
items:
type: string
limitAccessByEnvironment:
type: boolean
additionalRoles:
description: >-
Additional roles granted alongside this one, in
the same scope. Each is granted independently and
environment access is the union across them.
type: array
items:
type: object
properties:
role:
type: string
environments:
type: array
items:
type: string
limitAccessByEnvironment:
type: boolean
required:
- role
- environments
additionalProperties: false
required:
- project
- role
- environments
additionalProperties: false
additionalProperties: false
required:
- member
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
updatedMember:
$ref: '#/components/schemas/updatedMember'
required:
- updatedMember
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/members/{id}/role' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/members/{id}:
delete:
operationId: deleteMember
summary: Removes a single user from an organization
tags:
- members
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X DELETE 'https://api.growthbook.io/api/v1/members/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/queries/{id}:
get:
operationId: getQuery
summary: Get a single query
tags:
- queries
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
query:
$ref: '#/components/schemas/Query'
required:
- query
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/queries/abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/settings:
get:
operationId: getSettings
summary: Get organization settings
tags:
- settings
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
settings:
$ref: '#/components/schemas/Settings'
required:
- settings
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/settings' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/settings/approvals:
put:
operationId: putApprovalSettings
summary: Update approval settings
description: >-
Replace the approval requirements for feature flags, configs and
constants, for saved groups, and the Targeting Projects review mode.
Each family is replaced wholesale when supplied; omit one to leave it
unchanged.
tags:
- settings
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
requireReviews:
type: array
items:
$ref: '#/components/schemas/RequireReviewRuleInput'
approvalFlows:
type: object
properties:
savedGroups:
type: array
items:
$ref: '#/components/schemas/SavedGroupApprovalRule'
required:
- savedGroups
additionalProperties: false
targetingReviewMode:
type: array
items:
$ref: '#/components/schemas/TargetingReviewRule'
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
requireReviews:
type: array
items:
$ref: '#/components/schemas/RequireReviewRule'
approvalFlows:
$ref: '#/components/schemas/approvalFlows'
targetingReviewMode:
type: array
items:
$ref: '#/components/schemas/TargetingReviewRule'
required:
- requireReviews
- approvalFlows
- targetingReviewMode
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X PUT 'https://api.growthbook.io/api/v1/settings/approvals' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/version:
get:
operationId: getVersion
summary: Get the GrowthBook server version and build info
tags:
- meta
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
version:
type: string
commit:
type: string
date:
type: string
required:
- version
- commit
- date
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/version' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/confirmations/{id}:
get:
operationId: getConfirmation
summary: Get a confirmation
description: >-
Poll a held request until a person confirms or rejects it in GrowthBook.
Pass `wait` (seconds, max 30) to hold the request open until the status
changes.
tags:
- meta
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/wait'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
confirmation:
$ref: '#/components/schemas/Confirmation'
required:
- confirmation
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/confirmations/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/information-schema-tables/{tableId}:
get:
operationId: getInformationSchemaTable
summary: Get a single Information Schema Table by id
description: >-
Returns cached metadata for a specific table in the Data Source,
including columns and their data types. Not all data source types
support information schemas.
tags:
- data-sources
parameters:
- $ref: '#/components/parameters/tableId'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
informationSchemaTable:
$ref: '#/components/schemas/InformationSchemaTable'
required:
- informationSchemaTable
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/information-schema-tables/{tableId}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules:
get:
operationId: listRampSchedules
summary: Get all rampSchedules
description: |
Returns all ramp schedules for the organization, with optional filters.
tags:
- ramp-schedules
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/featureId'
- name: status
in: query
description: Filter by schedule status
schema:
description: Filter by schedule status
type: string
enum:
- pending
- ready
- running
- paused
- completed
- rolled-back
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
limit:
type: integer
offset:
type: integer
count:
type: integer
total:
type: integer
hasMore:
type: boolean
nextOffset:
anyOf:
- type: integer
- type: 'null'
rampSchedules:
type: array
items:
$ref: '#/components/schemas/RampSchedule'
required:
- limit
- offset
- count
- total
- hasMore
- nextOffset
- rampSchedules
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/ramp-schedules' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postRampSchedule
summary: Create a ramp schedule
description: >-
Creates a ramp schedule, optionally attached to a published feature rule
by passing `featureId` and `ruleId` together (the target is then
injected into every action). Attaching on creation skips the revision
review flow, so when the organization requires review anywhere it is
limited to credentials that may bypass approval. The reviewed way to
attach a plan is `PUT
/features/{id}/revisions/{version}/rules/{ruleId}/ramp-schedule`
followed by a publish. Without a target the schedule is a free-standing
skeleton in `pending` status. Requires a Pro plan or above.
tags:
- ramp-schedules
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
featureId:
type: string
ruleId:
type: string
environment:
type: string
steps:
type: array
items:
type: object
properties:
interval:
anyOf:
- type: number
exclusiveMinimum: 0
- type: 'null'
actions:
default: []
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:
default: false
type: boolean
holdConditions:
type: object
properties:
minSampleSize:
type: integer
exclusiveMinimum: 0
requiresApproval:
type: boolean
additionalProperties: false
required:
- interval
additionalProperties: false
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
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:
anyOf:
- type: string
format: date-time
- type: 'null'
cutoffDate:
anyOf:
- type: string
format: date-time
- type: 'null'
requiresStartApproval:
description: >-
When true, the ramp holds at step -1 with its rule disabled
(zero traffic) until a human approves the start via
/actions/approve-step. Composes with startDate.
anyOf:
- type: boolean
- type: 'null'
monitoringConfig:
anyOf:
- type: object
properties:
datasourceId:
type: string
exposureQuery:
description: >-
The assignment query, grouping its ID with the
identifier type analyzed on. Mutually exclusive with
the deprecated `exposureQueryId`.
type: object
properties:
id:
description: >-
The ID of one of the data source's assignment
queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the
query must declare. Required when selecting a
different assignment query that declares
several. Otherwise defaults to the current
identifier type, or the query's only one. Null
is treated as omitted, so a response's value can
be sent back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
exposureQueryId:
deprecated: true
description: >-
Deprecated: use `exposureQuery`. Rejected when
selecting a different assignment query that declares
several identifier types; set
`exposureQuery.identifierType` instead.
type: string
guardrailMetricIds:
minItems: 1
type: array
items:
type: string
signalMetricIds:
type: array
items:
type: string
monitoringMode:
type: string
enum:
- auto
- manual
autoUpdate:
type: boolean
autoRollback:
type: boolean
updateScheduleMinutes:
anyOf:
- type: number
minimum: 10
- type: 'null'
srmAction:
type: string
enum:
- warn
- hold
- rollback
noTrafficAction:
type: string
enum:
- warn
- hold
- rollback
multipleExposureAction:
type: string
enum:
- warn
- hold
- rollback
required:
- datasourceId
- guardrailMetricIds
additionalProperties: false
- type: 'null'
lockdownConfig:
type: object
properties:
mode:
type: string
enum:
- none
- locked
required:
- mode
additionalProperties: false
experimentHealthAction:
type: string
enum:
- rollback
- hold
- warn
templateId:
type: string
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/ramp-schedules' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/{id}/actions/start:
post:
operationId: startRampSchedule
summary: Start a ramp schedule
description: >
Transitions the schedule from `ready` to `running`. The schedule must
have
at least one target rule attached — a schedule created without targets
starts
in `pending` and moves to `ready` automatically when the first target is
attached via `/actions/add-target`.
The first step is processed immediately: interval-free steps advance
right
away; interval-based steps arm a timer. Once started, use
`/actions/pause`
to halt, `/actions/advance` to skip steps, or `/actions/rollback` to
revert.
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/start'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/{id}/actions/pause:
post:
operationId: pauseRampSchedule
summary: Pause a ramp schedule
description: >
Pauses a `running` schedule. Traffic percentages are frozen at their
current
values; no step advancement happens while paused. Records `pausedAt` so
that
interval timing can be correctly offset when the schedule resumes.
Use `/actions/resume` to continue from the same step, or
`/actions/rollback`
to revert all rule effects entirely.
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/pause'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/{id}/actions/resume:
post:
operationId: resumeRampSchedule
summary: Resume a paused ramp schedule
description: >
Resumes a `paused` schedule without moving the current step. Timing
anchors
(`phaseStartedAt`, `startedAt`) are shifted forward by the pause
duration so
that interval-based steps continue from where they left off rather than
restarting their clock.
Does **not** advance to the next step — use `/actions/advance` if you
also
want to skip the remainder of the current step.
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/resume'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/{id}/actions/rollback:
post:
operationId: rollbackRampSchedule
summary: Roll back a ramp schedule
description: >
Rewinds all ramp effects (rule coverage, targeting, etc.) to the
starting
position and lands in terminal `rolled-back` status. The reason is
persisted
as `lastRollbackReason` (prefixed with `Manual: `) and surfaced in the
UI.
This is also the correct response to a monitoring alert — when the
`/status` endpoint returns `decision: "rollback"` or signals include
`guardrail-failing`, call this endpoint with a descriptive `reason`.
From this terminal state the schedule can be brought back to `ready` via
`/actions/restart`, after which `/actions/start` will run it again.
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
reason:
type: string
maxLength: 200
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/rollback'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/{id}/actions/restart:
post:
operationId: restartRampSchedule
summary: Restart a terminal ramp schedule
description: >
Brings a `rolled-back` (or `completed`) schedule back into `running` in
a
single call. Any prior start-on-date delays are cleared (`startedAt`,
`phaseStartedAt`, etc. are reset), `currentStepIndex` is normalised to
`-1`, then the same logic as `/actions/start` runs to apply start
actions
and advance through immediately-eligible steps.
The rollback that preceded this already rewound rule effects to the
starting position; this endpoint does **not** re-execute that rewind for
`rolled-back` schedules. `completed` schedules are defensively rewound
first.
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/restart'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/{id}/actions/jump:
post:
operationId: jumpRampSchedule
summary: Jump to a specific step
description: >
Teleports the schedule to `targetStepIndex` (forward or backward) and
leaves
it `paused`. Resets timing anchors so the destination step's interval
starts
fresh when the schedule is next resumed or started.
Pass `-1` to return to the pre-start position without applying rollback
rule
patches — useful for resetting a non-started schedule. For a full
traffic
revert, use `/actions/rollback` instead.
Accepts any non-terminal schedule status.
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
targetStepIndex:
description: Zero-based index of the step to jump to; -1 = pre-start
type: integer
minimum: -1
required:
- targetStepIndex
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/jump'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/{id}/actions/complete:
post:
operationId: completeRampSchedule
summary: Complete a ramp schedule immediately
description: >
Immediately applies the schedule's end-state rule patches (the
equivalent
of what would happen after the last step advances normally) and marks
the
schedule as `completed`, skipping any remaining steps.
Pass `disableRule: true` to also disable the linked rule (equivalent to
the cutoff-date-driven completion).
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
disableRule:
type: boolean
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/complete'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/{id}/actions/approve-step:
post:
operationId: approveStepRampSchedule
summary: Approve the pending approval gate
description: >
Clears whichever approval gate is currently pending on the schedule:
- **Start gate** — a schedule created with `requiresStartApproval` sits
in `ready` at step -1 with its rule disabled (zero traffic). Approving
starts the ramp (or, if a future `startDate` is set, arms it to start on
that date).
- **Step gate** — the `holdConditions.requiresApproval` gate on the
current step of a `running` schedule.
For a step gate, approval is the **final** gate: it can only be granted
once every other hold has cleared. This endpoint rejects the request
(`400`) if the step is not yet ready — while the interval timer is still
counting down, or (for monitored steps) before fresh analysis is
available or while a guardrail/health signal is failing. Poll `/status`
and call this once it reports awaiting approval.
**Non-monitored steps**: once the interval has elapsed, approving clears
the last hold and advances immediately, chaining through subsequent
instant steps.
**Monitored steps**: approving clears the last hold and the agenda
advances on its next tick (re-checking analysis first).
Different from `/actions/advance`: `approve-step` works within the
normal evaluation flow and refuses to skip ahead of the interval or any
other unmet gate. Use `/actions/advance` to bypass all remaining holds.
Requires update + publish (start gate) or review (step gate) permissions
for the associated feature.
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/approve-step'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/{id}/actions/add-target:
post:
operationId: addTargetRampSchedule
summary: Add a target rule to a ramp schedule
description: >
Attaches an additional feature rule to this ramp schedule. The `ruleId`
must identify a rule that is already published and must not already be
controlled by another schedule. `environment` is accepted for backward
compatibility with pre-v2 ramps but is deprecated and no longer
required.
This skips the revision review flow, so when the organization requires
review
anywhere it is limited to credentials that may bypass approval. The
reviewed way
to attach a plan is `PUT
/features/{id}/revisions/{version}/rules/{ruleId}/ramp-schedule`
followed by a publish.
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
featureId:
type: string
ruleId:
type: string
environment:
deprecated: true
description: >-
Deprecated pre-v2 disambiguator; ignored on v2 rules where
`rule.id` is uniquely sufficient.
type: string
required:
- featureId
- ruleId
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/add-target'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/{id}/actions/eject-target:
post:
operationId: ejectTargetRampSchedule
summary: Remove a target rule from a ramp schedule
description: >
Detaches a target rule from this ramp schedule. Identify the target
either
by its `targetId` or by the `[ruleId, environment]` pair.
If this is the last target on the schedule, the schedule is deleted
entirely
and the response contains `deleted: true` instead of `rampSchedule`.
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
targetId:
description: Target ID (from the targets array)
type: string
ruleId:
description: Rule ID — use as an alternative to targetId
type: string
environment:
deprecated: true
description: >-
Deprecated pre-v2 disambiguator. Optional when used with
ruleId; omit on v2 ramps.
type: string
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
anyOf:
- type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
- type: object
properties:
deleted:
type: boolean
rampScheduleId:
type: string
required:
- deleted
- rampScheduleId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/eject-target'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/{id}/actions/advance:
post:
operationId: apiAdvanceRampSchedule
summary: Advance to the next step, overriding any holds
description: >
Moves the schedule to the next step, bypassing **all** hold conditions —
interval, min sample size, and monitoring signal holds. Accepts
`running`
or `paused` status; if paused, the schedule is implicitly resumed
(timing
anchors recalculated) before the step moves.
**Approval gate**: if the current step has an unsatisfied
`holdConditions.requiresApproval` gate, this endpoint returns **409** by
default. Either call `/actions/approve-step` first (recommended), or
pass
`force: true` to override the approval gate. `force: true` requires
`FlagsBypassApprovals` permission and is logged in the audit trail.
**Two common uses:**
- **Post-interval monitoring hold** (`decision: "hold"`, interval
elapsed): the
step timer has completed but a signal or guardrail is flagging concern. Use
this after reviewing the `/status` health summary and deciding to accept the
risk and proceed.
- **Hard override**: skip a step regardless of where it is in its
interval or
hold conditions (CI gate, external deployment pipeline).
When to use other actions instead:
- **`/actions/resume`** — restores a paused schedule without moving the
step.
- **`/actions/approve-step`** — clears only the approval gate; other
conditions
still resolve naturally.
- **`/actions/rollback`** — preferred response when `decision:
"rollback"` or
signals include `guardrail-failing`.
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
reason:
description: Reason for advancing
type: string
force:
description: >-
Bypass a pending approval gate on the current step. Requires
admin-level (`FlagsBypassApprovals`) permission. When
omitted or `false`, a 409 is returned if the step has an
unsatisfied `holdConditions.requiresApproval` gate. 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
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/advance'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/{id}/status:
get:
operationId: getRampScheduleStatus
summary: Get ramp schedule status summary
description: >-
Returns a real-time status summary for a ramp schedule: current step,
overall health decision, traffic quality, and per-metric effect sizes.
Designed for CI pipeline integrations and monitoring dashboards that
need a single call to determine whether it is safe to advance.
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
id:
type: string
status:
type: string
currentStepIndex:
type: number
totalSteps:
type: number
lockdownMode:
type: string
startedAt:
anyOf:
- type: string
- type: 'null'
lastRollbackAt:
anyOf:
- type: string
- type: 'null'
lastRollbackReason:
anyOf:
- type: string
- type: 'null'
monitoring:
$ref: '#/components/schemas/monitoring'
healthSummary:
$ref: '#/components/schemas/healthSummary'
required:
- id
- status
- currentStepIndex
- totalSteps
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/ramp-schedules/{id}/status' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/{id}/actions/set-monitoring-mode:
post:
operationId: setMonitoringModeRampSchedule
summary: Set ramp monitoring mode
description: >
Sets the user preference for ramp monitoring updates. In `manual` mode,
automatic snapshot scheduling is disabled and operators must click
Update manually. In `auto` mode, snapshots run automatically when the
current step is monitored and the ramp is running.
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
monitoringMode:
description: >-
`auto` schedules snapshots automatically while allowed by
ramp state. `manual` disables agenda updates and relies on
manual Update clicks.
type: string
enum:
- auto
- manual
required:
- monitoringMode
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
id: RampSchedule
type: object
properties:
id:
description: Unique identifier (rs_ prefix)
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
name:
type: string
entityType:
type: string
enum:
- feature
entityId:
type: string
targets:
description: Controlled entity references
type: array
items:
$ref: '#/components/schemas/targets'
startActions:
description: >-
Actions that restore controlled rules to their pre-ramp
state. Applied when rolling back or jumping to start, and
the base every step accumulates on; the only place a plan
can set hashAttribute, seed or hashVersion.
type: array
items:
$ref: '#/components/schemas/startActions'
steps:
description: Ordered ramp steps
type: array
items:
$ref: '#/components/schemas/steps'
endActions:
description: >-
Actions applied on top of all step patches when the ramp
completes. Represents the final desired rule state.
type: array
items:
$ref: '#/components/schemas/endActions'
startDate:
description: >-
When the ramp fires. Absent/null means immediately on
publish; set to a future datetime to delay start and keep
the rule disabled until that time.
anyOf:
- type: string
format: date-time
- type: 'null'
cutoffDate:
description: >-
Rule-level kill date. When reached, the ramp is completed
and the rule is disabled (enabled=false). Use for
time-boxed rules that must stop serving on a fixed date
regardless of ramp progress. Set to null to clear.
anyOf:
- type: string
format: date-time
- type: 'null'
requiresStartApproval:
description: >-
When true, the ramp holds at step -1 with its rule
disabled (zero traffic) until a human approves the start
via /actions/approve-step. Composes with startDate ('hold
until approved, then arm for that date').
type: boolean
startApprovedAt:
description: >-
When the current launch's start was approved. Cleared on
every return to step -1 (publish, rollback), re-arming the
approval gate.
anyOf:
- type: string
format: date-time
- type: 'null'
status:
type: string
enum:
- pending
- ready
- running
- paused
- completed
- rolled-back
currentStepIndex:
description: Index of current step; -1 = not yet started
type: integer
minimum: -1
startedAt:
anyOf:
- type: string
format: date-time
- type: 'null'
phaseStartedAt:
description: >-
Anchor for cumulative interval timing; resets after each
approval gate is satisfied
anyOf:
- type: string
format: date-time
- type: 'null'
pausedAt:
anyOf:
- type: string
format: date-time
- type: 'null'
nextStepAt:
description: >-
When the current step's time gate elapses; null for steps
with no interval (pure approval gates) and terminal states
anyOf:
- type: string
format: date-time
- type: 'null'
nextProcessAt:
anyOf:
- type: string
format: date-time
- type: 'null'
elapsedMs:
description: >-
Milliseconds since startedAt (computed at response time,
not stored)
anyOf:
- type: integer
- type: 'null'
lockdownConfig:
$ref: '#/components/schemas/lockdownConfig'
monitoringConfig:
anyOf:
- 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
- type: 'null'
experimentHealthAction:
type: string
enum:
- rollback
- hold
- warn
currentStepEnteredAt:
anyOf:
- type: string
format: date-time
- type: 'null'
stepApproval:
description: >-
Approval record for the current step. Valid only while
`stepApproval.stepIndex === currentStepIndex`.
anyOf:
- type: object
properties:
stepIndex:
description: Index of the step that was approved.
type: integer
approvedAt:
description: When the approval was granted.
type: string
format: date-time
approvedBy:
description: >-
Who approved: the approver's user ID, or the API
key's ID when a key approved as itself.
type: string
approvedByUser:
description: The approver, with an API key's name.
$ref: '#/components/schemas/EventUser'
context:
description: Surface through which the approval was granted.
type: string
enum:
- ui
- api
required:
- stepIndex
- approvedAt
- approvedBy
- context
additionalProperties: false
- type: 'null'
awaitingApproval:
description: >-
Computed at read time: whether a human approval is the
gate blocking the schedule right now — either the
start-approval gate (`requiresStartApproval` before step
0) or the current step's `holdConditions.requiresApproval`
once its time hold (if any) has elapsed. Paused schedules
report `false` (the pause is the blocking gate). For
monitored steps the approve-step endpoint may still reject
an approval until analysis-based gates clear.
type: boolean
monitoringStartDate:
description: >-
When the monitored section most recently started (first
monitored step entered). Used for no-traffic grace period
gating.
anyOf:
- type: string
format: date-time
- type: 'null'
lastRollbackAt:
anyOf:
- type: string
format: date-time
- type: 'null'
lastRollbackReason:
anyOf:
- type: string
- type: 'null'
monitoringStatus:
description: >-
Read-only monitoring status. Present when monitoringConfig
is set.
anyOf:
- type: object
properties:
safeRolloutId:
anyOf:
- type: string
- type: 'null'
monitoringMode:
description: >-
User-selected monitoring mode. `auto` schedules
snapshots automatically; `manual` requires
clicking Update.
type: string
enum:
- auto
- manual
autoUpdate:
description: >-
Legacy alias for auto-update behavior. Prefer
`monitoringMode` (`auto` means true, `manual`
means false).
type: boolean
effectiveAutoUpdate:
description: >-
Computed runtime flag. True only when monitoring
mode is auto and schedule state allows automatic
snapshot scheduling.
type: boolean
blockedReason:
description: >-
When `effectiveAutoUpdate` is false, this
describes the computed reason auto-updates are
currently blocked.
anyOf:
- type: string
- type: 'null'
nextSnapshotAt:
description: When the next automatic snapshot query will run
anyOf:
- type: string
format: date-time
- type: 'null'
currentStepMonitored:
description: >-
Whether the step at currentStepIndex has
monitoring enabled
type: boolean
required:
- monitoringMode
- autoUpdate
- effectiveAutoUpdate
- currentStepMonitored
additionalProperties: false
- type: 'null'
required:
- id
- dateCreated
- dateUpdated
- name
- entityType
- entityId
- targets
- steps
- status
- currentStepIndex
- nextStepAt
- awaitingApproval
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/set-monitoring-mode'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/{id}/actions/set-auto-update:
post:
operationId: setAutoUpdateRampSchedule
summary: Toggle automatic monitoring updates
description: >
Deprecated alias for setting monitoring mode. Prefer
`/actions/set-monitoring-mode`.
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
enabled:
description: >-
Legacy alias for monitoring mode (`true` => auto, `false` =>
manual).
type: boolean
required:
- enabled
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
id: RampSchedule
type: object
properties:
id:
description: Unique identifier (rs_ prefix)
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
name:
type: string
entityType:
type: string
enum:
- feature
entityId:
type: string
targets:
description: Controlled entity references
type: array
items:
$ref: '#/components/schemas/targets'
startActions:
description: >-
Actions that restore controlled rules to their pre-ramp
state. Applied when rolling back or jumping to start, and
the base every step accumulates on; the only place a plan
can set hashAttribute, seed or hashVersion.
type: array
items:
$ref: '#/components/schemas/startActions'
steps:
description: Ordered ramp steps
type: array
items:
$ref: '#/components/schemas/steps'
endActions:
description: >-
Actions applied on top of all step patches when the ramp
completes. Represents the final desired rule state.
type: array
items:
$ref: '#/components/schemas/endActions'
startDate:
description: >-
When the ramp fires. Absent/null means immediately on
publish; set to a future datetime to delay start and keep
the rule disabled until that time.
anyOf:
- type: string
format: date-time
- type: 'null'
cutoffDate:
description: >-
Rule-level kill date. When reached, the ramp is completed
and the rule is disabled (enabled=false). Use for
time-boxed rules that must stop serving on a fixed date
regardless of ramp progress. Set to null to clear.
anyOf:
- type: string
format: date-time
- type: 'null'
requiresStartApproval:
description: >-
When true, the ramp holds at step -1 with its rule
disabled (zero traffic) until a human approves the start
via /actions/approve-step. Composes with startDate ('hold
until approved, then arm for that date').
type: boolean
startApprovedAt:
description: >-
When the current launch's start was approved. Cleared on
every return to step -1 (publish, rollback), re-arming the
approval gate.
anyOf:
- type: string
format: date-time
- type: 'null'
status:
type: string
enum:
- pending
- ready
- running
- paused
- completed
- rolled-back
currentStepIndex:
description: Index of current step; -1 = not yet started
type: integer
minimum: -1
startedAt:
anyOf:
- type: string
format: date-time
- type: 'null'
phaseStartedAt:
description: >-
Anchor for cumulative interval timing; resets after each
approval gate is satisfied
anyOf:
- type: string
format: date-time
- type: 'null'
pausedAt:
anyOf:
- type: string
format: date-time
- type: 'null'
nextStepAt:
description: >-
When the current step's time gate elapses; null for steps
with no interval (pure approval gates) and terminal states
anyOf:
- type: string
format: date-time
- type: 'null'
nextProcessAt:
anyOf:
- type: string
format: date-time
- type: 'null'
elapsedMs:
description: >-
Milliseconds since startedAt (computed at response time,
not stored)
anyOf:
- type: integer
- type: 'null'
lockdownConfig:
$ref: '#/components/schemas/lockdownConfig'
monitoringConfig:
anyOf:
- 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
- type: 'null'
experimentHealthAction:
type: string
enum:
- rollback
- hold
- warn
currentStepEnteredAt:
anyOf:
- type: string
format: date-time
- type: 'null'
stepApproval:
description: >-
Approval record for the current step. Valid only while
`stepApproval.stepIndex === currentStepIndex`.
anyOf:
- type: object
properties:
stepIndex:
description: Index of the step that was approved.
type: integer
approvedAt:
description: When the approval was granted.
type: string
format: date-time
approvedBy:
description: >-
Who approved: the approver's user ID, or the API
key's ID when a key approved as itself.
type: string
approvedByUser:
description: The approver, with an API key's name.
$ref: '#/components/schemas/EventUser'
context:
description: Surface through which the approval was granted.
type: string
enum:
- ui
- api
required:
- stepIndex
- approvedAt
- approvedBy
- context
additionalProperties: false
- type: 'null'
awaitingApproval:
description: >-
Computed at read time: whether a human approval is the
gate blocking the schedule right now — either the
start-approval gate (`requiresStartApproval` before step
0) or the current step's `holdConditions.requiresApproval`
once its time hold (if any) has elapsed. Paused schedules
report `false` (the pause is the blocking gate). For
monitored steps the approve-step endpoint may still reject
an approval until analysis-based gates clear.
type: boolean
monitoringStartDate:
description: >-
When the monitored section most recently started (first
monitored step entered). Used for no-traffic grace period
gating.
anyOf:
- type: string
format: date-time
- type: 'null'
lastRollbackAt:
anyOf:
- type: string
format: date-time
- type: 'null'
lastRollbackReason:
anyOf:
- type: string
- type: 'null'
monitoringStatus:
description: >-
Read-only monitoring status. Present when monitoringConfig
is set.
anyOf:
- type: object
properties:
safeRolloutId:
anyOf:
- type: string
- type: 'null'
monitoringMode:
description: >-
User-selected monitoring mode. `auto` schedules
snapshots automatically; `manual` requires
clicking Update.
type: string
enum:
- auto
- manual
autoUpdate:
description: >-
Legacy alias for auto-update behavior. Prefer
`monitoringMode` (`auto` means true, `manual`
means false).
type: boolean
effectiveAutoUpdate:
description: >-
Computed runtime flag. True only when monitoring
mode is auto and schedule state allows automatic
snapshot scheduling.
type: boolean
blockedReason:
description: >-
When `effectiveAutoUpdate` is false, this
describes the computed reason auto-updates are
currently blocked.
anyOf:
- type: string
- type: 'null'
nextSnapshotAt:
description: When the next automatic snapshot query will run
anyOf:
- type: string
format: date-time
- type: 'null'
currentStepMonitored:
description: >-
Whether the step at currentStepIndex has
monitoring enabled
type: boolean
required:
- monitoringMode
- autoUpdate
- effectiveAutoUpdate
- currentStepMonitored
additionalProperties: false
- type: 'null'
required:
- id
- dateCreated
- dateUpdated
- name
- entityType
- entityId
- targets
- steps
- status
- currentStepIndex
- nextStepAt
- awaitingApproval
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/set-auto-update'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/{id}/monitoring:
put:
operationId: updateRampScheduleMonitoring
summary: Update ramp monitoring configuration
description: >
Replaces the monitoring configuration. Health-action thresholds
(`srmAction`, `noTrafficAction`, etc.) can be updated at any time.
Once a linked SafeRollout has started, `datasourceId`,
`exposureQueryId`, the metric IDs and the snapshot cadence are all
locked — stop and recreate the schedule to change the data source.
Changes to guardrail or signal metric IDs take effect on the next
analysis run.
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
description: >-
Full replacement of the monitoring configuration. `datasourceId`
and `exposureQuery` cannot be changed while a monitoring
experiment is active — stop the schedule first.
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. Mutually exclusive with the deprecated
`exposureQueryId`.
type: object
properties:
id:
description: The ID of one of the data source's assignment queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the query must
declare. Required when selecting a different assignment
query that declares several. Otherwise defaults to the
current identifier type, or the query's only one. Null
is treated as omitted, so a response's value can be sent
back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
exposureQueryId:
deprecated: true
description: >-
Deprecated: use `exposureQuery`. Rejected when selecting a
different assignment query that declares several identifier
types; set `exposureQuery.identifierType` instead.
type: string
required:
- datasourceId
- guardrailMetricIds
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
id: RampSchedule
type: object
properties:
id:
description: Unique identifier (rs_ prefix)
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
name:
type: string
entityType:
type: string
enum:
- feature
entityId:
type: string
targets:
description: Controlled entity references
type: array
items:
$ref: '#/components/schemas/targets'
startActions:
description: >-
Actions that restore controlled rules to their pre-ramp
state. Applied when rolling back or jumping to start, and
the base every step accumulates on; the only place a plan
can set hashAttribute, seed or hashVersion.
type: array
items:
$ref: '#/components/schemas/startActions'
steps:
description: Ordered ramp steps
type: array
items:
$ref: '#/components/schemas/steps'
endActions:
description: >-
Actions applied on top of all step patches when the ramp
completes. Represents the final desired rule state.
type: array
items:
$ref: '#/components/schemas/endActions'
startDate:
description: >-
When the ramp fires. Absent/null means immediately on
publish; set to a future datetime to delay start and keep
the rule disabled until that time.
anyOf:
- type: string
format: date-time
- type: 'null'
cutoffDate:
description: >-
Rule-level kill date. When reached, the ramp is completed
and the rule is disabled (enabled=false). Use for
time-boxed rules that must stop serving on a fixed date
regardless of ramp progress. Set to null to clear.
anyOf:
- type: string
format: date-time
- type: 'null'
requiresStartApproval:
description: >-
When true, the ramp holds at step -1 with its rule
disabled (zero traffic) until a human approves the start
via /actions/approve-step. Composes with startDate ('hold
until approved, then arm for that date').
type: boolean
startApprovedAt:
description: >-
When the current launch's start was approved. Cleared on
every return to step -1 (publish, rollback), re-arming the
approval gate.
anyOf:
- type: string
format: date-time
- type: 'null'
status:
type: string
enum:
- pending
- ready
- running
- paused
- completed
- rolled-back
currentStepIndex:
description: Index of current step; -1 = not yet started
type: integer
minimum: -1
startedAt:
anyOf:
- type: string
format: date-time
- type: 'null'
phaseStartedAt:
description: >-
Anchor for cumulative interval timing; resets after each
approval gate is satisfied
anyOf:
- type: string
format: date-time
- type: 'null'
pausedAt:
anyOf:
- type: string
format: date-time
- type: 'null'
nextStepAt:
description: >-
When the current step's time gate elapses; null for steps
with no interval (pure approval gates) and terminal states
anyOf:
- type: string
format: date-time
- type: 'null'
nextProcessAt:
anyOf:
- type: string
format: date-time
- type: 'null'
elapsedMs:
description: >-
Milliseconds since startedAt (computed at response time,
not stored)
anyOf:
- type: integer
- type: 'null'
lockdownConfig:
$ref: '#/components/schemas/lockdownConfig'
monitoringConfig:
anyOf:
- 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
- type: 'null'
experimentHealthAction:
type: string
enum:
- rollback
- hold
- warn
currentStepEnteredAt:
anyOf:
- type: string
format: date-time
- type: 'null'
stepApproval:
description: >-
Approval record for the current step. Valid only while
`stepApproval.stepIndex === currentStepIndex`.
anyOf:
- type: object
properties:
stepIndex:
description: Index of the step that was approved.
type: integer
approvedAt:
description: When the approval was granted.
type: string
format: date-time
approvedBy:
description: >-
Who approved: the approver's user ID, or the API
key's ID when a key approved as itself.
type: string
approvedByUser:
description: The approver, with an API key's name.
$ref: '#/components/schemas/EventUser'
context:
description: Surface through which the approval was granted.
type: string
enum:
- ui
- api
required:
- stepIndex
- approvedAt
- approvedBy
- context
additionalProperties: false
- type: 'null'
awaitingApproval:
description: >-
Computed at read time: whether a human approval is the
gate blocking the schedule right now — either the
start-approval gate (`requiresStartApproval` before step
0) or the current step's `holdConditions.requiresApproval`
once its time hold (if any) has elapsed. Paused schedules
report `false` (the pause is the blocking gate). For
monitored steps the approve-step endpoint may still reject
an approval until analysis-based gates clear.
type: boolean
monitoringStartDate:
description: >-
When the monitored section most recently started (first
monitored step entered). Used for no-traffic grace period
gating.
anyOf:
- type: string
format: date-time
- type: 'null'
lastRollbackAt:
anyOf:
- type: string
format: date-time
- type: 'null'
lastRollbackReason:
anyOf:
- type: string
- type: 'null'
monitoringStatus:
description: >-
Read-only monitoring status. Present when monitoringConfig
is set.
anyOf:
- type: object
properties:
safeRolloutId:
anyOf:
- type: string
- type: 'null'
monitoringMode:
description: >-
User-selected monitoring mode. `auto` schedules
snapshots automatically; `manual` requires
clicking Update.
type: string
enum:
- auto
- manual
autoUpdate:
description: >-
Legacy alias for auto-update behavior. Prefer
`monitoringMode` (`auto` means true, `manual`
means false).
type: boolean
effectiveAutoUpdate:
description: >-
Computed runtime flag. True only when monitoring
mode is auto and schedule state allows automatic
snapshot scheduling.
type: boolean
blockedReason:
description: >-
When `effectiveAutoUpdate` is false, this
describes the computed reason auto-updates are
currently blocked.
anyOf:
- type: string
- type: 'null'
nextSnapshotAt:
description: When the next automatic snapshot query will run
anyOf:
- type: string
format: date-time
- type: 'null'
currentStepMonitored:
description: >-
Whether the step at currentStepIndex has
monitoring enabled
type: boolean
required:
- monitoringMode
- autoUpdate
- effectiveAutoUpdate
- currentStepMonitored
additionalProperties: false
- type: 'null'
required:
- id
- dateCreated
- dateUpdated
- name
- entityType
- entityId
- targets
- steps
- status
- currentStepIndex
- nextStepAt
- awaitingApproval
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/ramp-schedules/{id}/monitoring' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/{id}/lockdown:
put:
operationId: updateRampScheduleLockdown
summary: Update ramp lockdown configuration
description: >
Sets the lockdown mode. `locked` prevents other users from publishing
unrelated changes to the parent feature while the ramp is running —
useful when you want to ensure no external edits interfere with a live
rollout. It does **not** affect the ramp's own auto-advancement or
monitoring behavior; use `actions/pause` to halt the ramp itself. `none`
removes the publishing restriction.
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
mode:
type: string
enum:
- none
- locked
required:
- mode
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
id: RampSchedule
type: object
properties:
id:
description: Unique identifier (rs_ prefix)
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
name:
type: string
entityType:
type: string
enum:
- feature
entityId:
type: string
targets:
description: Controlled entity references
type: array
items:
$ref: '#/components/schemas/targets'
startActions:
description: >-
Actions that restore controlled rules to their pre-ramp
state. Applied when rolling back or jumping to start, and
the base every step accumulates on; the only place a plan
can set hashAttribute, seed or hashVersion.
type: array
items:
$ref: '#/components/schemas/startActions'
steps:
description: Ordered ramp steps
type: array
items:
$ref: '#/components/schemas/steps'
endActions:
description: >-
Actions applied on top of all step patches when the ramp
completes. Represents the final desired rule state.
type: array
items:
$ref: '#/components/schemas/endActions'
startDate:
description: >-
When the ramp fires. Absent/null means immediately on
publish; set to a future datetime to delay start and keep
the rule disabled until that time.
anyOf:
- type: string
format: date-time
- type: 'null'
cutoffDate:
description: >-
Rule-level kill date. When reached, the ramp is completed
and the rule is disabled (enabled=false). Use for
time-boxed rules that must stop serving on a fixed date
regardless of ramp progress. Set to null to clear.
anyOf:
- type: string
format: date-time
- type: 'null'
requiresStartApproval:
description: >-
When true, the ramp holds at step -1 with its rule
disabled (zero traffic) until a human approves the start
via /actions/approve-step. Composes with startDate ('hold
until approved, then arm for that date').
type: boolean
startApprovedAt:
description: >-
When the current launch's start was approved. Cleared on
every return to step -1 (publish, rollback), re-arming the
approval gate.
anyOf:
- type: string
format: date-time
- type: 'null'
status:
type: string
enum:
- pending
- ready
- running
- paused
- completed
- rolled-back
currentStepIndex:
description: Index of current step; -1 = not yet started
type: integer
minimum: -1
startedAt:
anyOf:
- type: string
format: date-time
- type: 'null'
phaseStartedAt:
description: >-
Anchor for cumulative interval timing; resets after each
approval gate is satisfied
anyOf:
- type: string
format: date-time
- type: 'null'
pausedAt:
anyOf:
- type: string
format: date-time
- type: 'null'
nextStepAt:
description: >-
When the current step's time gate elapses; null for steps
with no interval (pure approval gates) and terminal states
anyOf:
- type: string
format: date-time
- type: 'null'
nextProcessAt:
anyOf:
- type: string
format: date-time
- type: 'null'
elapsedMs:
description: >-
Milliseconds since startedAt (computed at response time,
not stored)
anyOf:
- type: integer
- type: 'null'
lockdownConfig:
$ref: '#/components/schemas/lockdownConfig'
monitoringConfig:
anyOf:
- 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
- type: 'null'
experimentHealthAction:
type: string
enum:
- rollback
- hold
- warn
currentStepEnteredAt:
anyOf:
- type: string
format: date-time
- type: 'null'
stepApproval:
description: >-
Approval record for the current step. Valid only while
`stepApproval.stepIndex === currentStepIndex`.
anyOf:
- type: object
properties:
stepIndex:
description: Index of the step that was approved.
type: integer
approvedAt:
description: When the approval was granted.
type: string
format: date-time
approvedBy:
description: >-
Who approved: the approver's user ID, or the API
key's ID when a key approved as itself.
type: string
approvedByUser:
description: The approver, with an API key's name.
$ref: '#/components/schemas/EventUser'
context:
description: Surface through which the approval was granted.
type: string
enum:
- ui
- api
required:
- stepIndex
- approvedAt
- approvedBy
- context
additionalProperties: false
- type: 'null'
awaitingApproval:
description: >-
Computed at read time: whether a human approval is the
gate blocking the schedule right now — either the
start-approval gate (`requiresStartApproval` before step
0) or the current step's `holdConditions.requiresApproval`
once its time hold (if any) has elapsed. Paused schedules
report `false` (the pause is the blocking gate). For
monitored steps the approve-step endpoint may still reject
an approval until analysis-based gates clear.
type: boolean
monitoringStartDate:
description: >-
When the monitored section most recently started (first
monitored step entered). Used for no-traffic grace period
gating.
anyOf:
- type: string
format: date-time
- type: 'null'
lastRollbackAt:
anyOf:
- type: string
format: date-time
- type: 'null'
lastRollbackReason:
anyOf:
- type: string
- type: 'null'
monitoringStatus:
description: >-
Read-only monitoring status. Present when monitoringConfig
is set.
anyOf:
- type: object
properties:
safeRolloutId:
anyOf:
- type: string
- type: 'null'
monitoringMode:
description: >-
User-selected monitoring mode. `auto` schedules
snapshots automatically; `manual` requires
clicking Update.
type: string
enum:
- auto
- manual
autoUpdate:
description: >-
Legacy alias for auto-update behavior. Prefer
`monitoringMode` (`auto` means true, `manual`
means false).
type: boolean
effectiveAutoUpdate:
description: >-
Computed runtime flag. True only when monitoring
mode is auto and schedule state allows automatic
snapshot scheduling.
type: boolean
blockedReason:
description: >-
When `effectiveAutoUpdate` is false, this
describes the computed reason auto-updates are
currently blocked.
anyOf:
- type: string
- type: 'null'
nextSnapshotAt:
description: When the next automatic snapshot query will run
anyOf:
- type: string
format: date-time
- type: 'null'
currentStepMonitored:
description: >-
Whether the step at currentStepIndex has
monitoring enabled
type: boolean
required:
- monitoringMode
- autoUpdate
- effectiveAutoUpdate
- currentStepMonitored
additionalProperties: false
- type: 'null'
required:
- id
- dateCreated
- dateUpdated
- name
- entityType
- entityId
- targets
- steps
- status
- currentStepIndex
- nextStepAt
- awaitingApproval
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/ramp-schedules/{id}/lockdown' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/{id}/steps:
put:
operationId: updateRampScheduleSteps
summary: Update ramp schedule steps
description: >
Fully replaces the steps array for a ramp schedule. Only allowed when
the schedule is in a non-running, non-terminal state (`ready`,
`pending`, or `paused`). Pause a running schedule first; restart a
terminal schedule first.
On a schedule attached to a rule this skips the revision review flow, so
when the organization requires review anywhere it is limited to
credentials that may bypass approval.
**Step actions** (coverage/targeting patches) are not accepted here —
they change the SDK payload and must go through a feature revision
draft. Existing step actions are preserved for each position. Use `PUT
/v2/features/:id/revisions/:version/rules/:ruleId/ramp-schedule` to
modify coverage/targeting.
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
steps:
description: >-
Full replacement of the steps array. Step-level coverage
patches (`actions`) are intentionally excluded — those
require a revision publish because they change the SDK
payload. Use the revision flow to modify coverage/targeting;
use this endpoint to update monitoring flags and hold
conditions.
type: array
items:
type: object
properties:
actions:
description: >-
Read-only; ignored on write. Accepted so a GET
response can be posted back unchanged.
interval:
description: >-
Hold duration in seconds before this step's gates are
evaluated. `null` means no time gate.
anyOf:
- type: number
exclusiveMinimum: 0
- type: 'null'
monitored:
description: >-
When true, this step runs A/B traffic analysis while
active. Applies only to future steps — cannot be
changed on the currently executing step.
type: boolean
holdConditions:
description: >-
Additional gates that must clear before the step
advances: `minSampleSize` and/or `requiresApproval`.
type: object
properties:
minSampleSize:
type: integer
exclusiveMinimum: 0
requiresApproval:
type: boolean
additionalProperties: false
approvalNotes:
description: >-
Optional notes shown to approvers when the step is
awaiting approval.
anyOf:
- type: string
- type: 'null'
required:
- interval
additionalProperties: false
required:
- steps
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/ramp-schedules/{id}/steps' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/{id}/actions/refresh-monitoring:
post:
operationId: refreshMonitoringRampSchedule
summary: Trigger a manual monitoring update
description: >
Queues a new analysis snapshot for the schedule's monitoring experiment.
The snapshot runs asynchronously — poll `GET /ramp-schedules/:id/status`
until `snapshotAt` advances to confirm results are ready.
Only available when the schedule is within its monitored step window:
- Not in a terminal state (`completed` or `rolled-back`).
- Has at least one step with `monitored: true`.
- `currentStepIndex` is within `[firstMonitoredStepIndex,
lastMonitoredStepIndex]`.
Violating any condition returns **409 Conflict** with a descriptive
message.
Requires the `runQueries` permission on the configured datasource
(enforced via `canRunExperimentQueries`).
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/refresh-monitoring'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/actions/rollback:
post:
operationId: rollbackMatchingRampSchedules
summary: Roll back matching ramp schedules
description: >
Rolls back every `running` or `paused` ramp schedule that matches the
query
filters. Built for an alerting tool's webhook, such as a Datadog
monitor.
Each filter takes comma-separated values and matches any of them;
different
filters must all match. At least one filter is required.
Returns each matched schedule and whether the rollback was applied or
skipped,
for example because the API key can't publish its Feature Flag. Unknown
body
fields are ignored, so a tool can send its own payload.
tags: &ref_0
- ramp-schedules
parameters:
- name: environment
in: query
description: >-
Comma-separated environments. Matches ramps whose rules run in any
of them.
schema:
description: >-
Comma-separated environments. Matches ramps whose rules run in any
of them.
type: array
items:
type: string
explode: false
- $ref: '#/components/parameters/project'
- name: tag
in: query
description: >-
Comma-separated tags. Matches ramps on Feature Flags with any of
them.
schema:
description: >-
Comma-separated tags. Matches ramps on Feature Flags with any of
them.
type: array
items:
type: string
explode: false
- $ref: '#/components/parameters/feature'
- $ref: '#/components/parameters/customFields'
- $ref: '#/components/parameters/reason'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
reason:
description: >-
Recorded on each ramp, prefixed with `Alert: `. Use the
alert title and link.
type: string
additionalProperties: {}
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
rampSchedules:
type: array
items:
$ref: '#/components/schemas/MatchedRampSchedule'
required:
- rampSchedules
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/ramp-schedules/actions/rollback' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/actions/pause:
post:
operationId: pauseMatchingRampSchedules
summary: Pause matching ramp schedules
description: >
Pauses every `running` ramp schedule that matches the query filters.
Built
for an alerting tool's webhook, such as a Datadog monitor. Each schedule
stays
paused until someone calls `/actions/resume` on it.
Each filter takes comma-separated values and matches any of them;
different
filters must all match. With no filters, every running schedule is
paused,
for example during a site-wide outage.
Returns each matched schedule and whether the pause was applied or
skipped,
for example because the API key can't publish its Feature Flag. Unknown
body
fields are ignored, so a tool can send its own payload.
tags: *ref_0
parameters:
- name: environment
in: query
description: >-
Comma-separated environments. Matches ramps whose rules run in any
of them.
schema:
description: >-
Comma-separated environments. Matches ramps whose rules run in any
of them.
type: array
items:
type: string
explode: false
- $ref: '#/components/parameters/project'
- name: tag
in: query
description: >-
Comma-separated tags. Matches ramps on Feature Flags with any of
them.
schema:
description: >-
Comma-separated tags. Matches ramps on Feature Flags with any of
them.
type: array
items:
type: string
explode: false
- $ref: '#/components/parameters/feature'
- $ref: '#/components/parameters/customFields'
- $ref: '#/components/parameters/reason'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
reason:
description: >-
Recorded on each ramp, prefixed with `Alert: `. Use the
alert title and link.
type: string
additionalProperties: {}
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
rampSchedules:
type: array
items:
$ref: '#/components/schemas/MatchedRampSchedule'
required:
- rampSchedules
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/ramp-schedules/actions/pause' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/reports:
get:
operationId: listReports
summary: Get all reports
tags:
- reports
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- name: experimentId
in: query
description: Filter reports by experiment id
schema:
description: Filter reports by experiment id
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
reports:
type: array
items:
$ref: '#/components/schemas/Report'
required:
- reports
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/reports' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postReport
summary: Create a new report
tags:
- reports
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
experimentId:
description: The experiment to create a report for
type: string
title:
description: Report title (defaults to experiment name)
type: string
description:
description: Report description
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. When
omitted, it defaults to the requesting member: a personal
access token's owner, or the member an organization API key
assumes. An organization API key acting as itself leaves it
empty.
type: string
statsEngine:
description: Stats engine override
type: string
enum:
- bayesian
- frequentist
goalMetrics:
description: Goal metric IDs (defaults to experiment's goal metrics)
type: array
items:
type: string
secondaryMetrics:
description: >-
Secondary metric IDs (defaults to experiment's secondary
metrics)
type: array
items:
type: string
guardrailMetrics:
description: >-
Guardrail metric IDs (defaults to experiment's guardrail
metrics)
type: array
items:
type: string
activationMetric:
description: Activation metric ID
type: string
dimension:
description: Dimension to cut results by
type: string
dateStarted:
format: date-time
description: Analysis start date (ISO 8601)
type: string
dateEnded:
format: date-time
description: Analysis end date (ISO 8601)
type: string
regressionAdjustmentEnabled:
description: Enable CUPED regression adjustment
type: boolean
sequentialTestingEnabled:
description: Enable sequential testing
type: boolean
sequentialTestingTuningParameter:
description: Tuning parameter for sequential testing (frequentist only)
type: number
differenceType:
description: >-
How lifts are expressed in results. Defaults to experiment
setting.
type: string
enum:
- relative
- absolute
- scaled
attributionModel:
description: >-
Metric conversion window attribution model. Defaults to
experiment setting.
type: string
enum:
- firstExposure
- experimentDuration
- lookbackOverride
lookbackOverride:
description: >-
Lookback window when `attributionModel` is
`lookbackOverride`
anyOf:
- type: object
properties:
type:
type: string
const: date
value: {}
required:
- type
- value
additionalProperties: false
- type: object
properties:
type:
type: string
const: window
value:
type: number
minimum: 0
valueUnit:
type: string
enum:
- minutes
- hours
- days
- weeks
required:
- type
- value
- valueUnit
additionalProperties: false
metricOverrides:
description: >-
Per-metric window, prior, and regression-adjustment
overrides
type: array
items:
type: object
properties:
id:
type: string
windowType:
type: string
enum:
- conversion
- lookback
- ''
windowHours:
type: number
delayHours:
type: number
properPriorOverride:
type: boolean
properPriorEnabled:
type: boolean
properPriorMean:
type: number
properPriorStdDev:
type: number
exclusiveMinimum: 0
regressionAdjustmentOverride:
type: boolean
regressionAdjustmentEnabled:
type: boolean
regressionAdjustmentDays:
type: number
winRisk:
deprecated: true
description: No longer used. Accepted and ignored.
type: number
loseRisk:
deprecated: true
description: No longer used. Accepted and ignored.
type: number
required:
- id
additionalProperties: false
customMetricSlices:
description: Custom metric slice definitions
type: array
items:
type: object
properties:
slices:
type: array
items:
type: object
properties:
column:
type: string
levels:
type: array
items:
type: string
required:
- column
- levels
additionalProperties: false
required:
- slices
additionalProperties: false
segment:
description: >-
Segment ID to filter users by. Defaults to experiment
setting.
type: string
queryFilter:
description: >-
Raw SQL WHERE clause added to the exposure query. Defaults
to experiment setting.
type: string
skipPartialData:
description: >-
When true, exclude users who have not completed the full
conversion window.
type: boolean
shareLevel:
description: >-
Visibility of the created report. Defaults to `private`. Set
to `public` to receive a shareable `shareUrl` in the
response.
type: string
enum:
- public
- organization
- private
required:
- experimentId
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
report:
$ref: '#/components/schemas/Report'
required:
- report
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/reports' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/reports/{id}:
get:
operationId: getReport
summary: Get a single report
tags:
- reports
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
report:
$ref: '#/components/schemas/Report'
required:
- report
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/reports/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/reports/{id}/refresh:
post:
operationId: postReportRefresh
summary: Refresh a report by re-running its analysis
tags:
- reports
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
report:
$ref: '#/components/schemas/Report'
required:
- report
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X POST 'https://api.growthbook.io/api/v1/reports/{id}/refresh'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/reports/{id}/metadata:
put:
operationId: putReportMetadata
summary: Update report metadata (title, description, visibility)
tags:
- reports
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
description: Report title
type: string
description:
description: Report description
type: string
status:
description: UI lifecycle marker for the report
type: string
enum:
- published
- private
shareLevel:
description: >-
Visibility of the report. Setting to `public` enables a
shareable `shareUrl`; setting back to `organization` or
`private` revokes public access (the share token is
preserved, so re-publishing exposes the same URL).
type: string
enum:
- public
- organization
- private
editLevel:
description: >-
Who can edit the report in the GrowthBook UI. `organization`
allows any org member with the `createAnalyses` permission;
`private` restricts editing to the report owner.
type: string
enum:
- organization
- private
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
report:
$ref: '#/components/schemas/Report'
required:
- report
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT 'https://api.growthbook.io/api/v1/reports/{id}/metadata'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/reports/{id}/settings:
put:
operationId: putReportSettings
summary: Update report analysis settings
description: >-
Updates the analysis settings for an existing report. Changes are staged
and do not take effect until you call `POST /reports/:id/refresh`.
tags:
- reports
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
statsEngine:
description: Stats engine override
type: string
enum:
- bayesian
- frequentist
goalMetrics:
description: Goal metric IDs
type: array
items:
type: string
secondaryMetrics:
description: Secondary metric IDs
type: array
items:
type: string
guardrailMetrics:
description: Guardrail metric IDs
type: array
items:
type: string
activationMetric:
description: Activation metric ID
type: string
metricOverrides:
description: >-
Per-metric window, prior, and regression-adjustment
overrides
type: array
items:
type: object
properties:
id:
type: string
windowType:
type: string
enum:
- conversion
- lookback
- ''
windowHours:
type: number
delayHours:
type: number
properPriorOverride:
type: boolean
properPriorEnabled:
type: boolean
properPriorMean:
type: number
properPriorStdDev:
type: number
exclusiveMinimum: 0
regressionAdjustmentOverride:
type: boolean
regressionAdjustmentEnabled:
type: boolean
regressionAdjustmentDays:
type: number
winRisk:
deprecated: true
description: No longer used. Accepted and ignored.
type: number
loseRisk:
deprecated: true
description: No longer used. Accepted and ignored.
type: number
required:
- id
additionalProperties: false
customMetricSlices:
description: Custom metric slice definitions
type: array
items:
type: object
properties:
slices:
type: array
items:
type: object
properties:
column:
type: string
levels:
type: array
items:
type: string
required:
- column
- levels
additionalProperties: false
required:
- slices
additionalProperties: false
dimension:
description: Dimension to cut results by
type: string
differenceType:
description: How lifts are expressed in results
type: string
enum:
- relative
- absolute
- scaled
dateStarted:
format: date-time
description: Analysis start date (ISO 8601)
type: string
dateEnded:
description: >-
Analysis end date (ISO 8601). Pass `null` to clear the end
date and analyze through today.
anyOf:
- format: date-time
type: string
- type: 'null'
regressionAdjustmentEnabled:
description: Enable CUPED regression adjustment
type: boolean
sequentialTestingEnabled:
description: Enable sequential testing
type: boolean
sequentialTestingTuningParameter:
description: Tuning parameter for sequential testing (frequentist only)
type: number
attributionModel:
description: Metric conversion window attribution model
type: string
enum:
- firstExposure
- experimentDuration
- lookbackOverride
lookbackOverride:
description: >-
Lookback window when `attributionModel` is
`lookbackOverride`
anyOf:
- type: object
properties:
type:
type: string
const: date
value: {}
required:
- type
- value
additionalProperties: false
- type: object
properties:
type:
type: string
const: window
value:
type: number
minimum: 0
valueUnit:
type: string
enum:
- minutes
- hours
- days
- weeks
required:
- type
- value
- valueUnit
additionalProperties: false
segment:
description: Segment ID to filter users by
type: string
queryFilter:
description: Raw SQL WHERE clause added to the exposure query
type: string
skipPartialData:
description: >-
When true, exclude users who have not completed the full
conversion window
type: boolean
variations:
description: >-
Override variation names, keys, or traffic weights used in
this report. Weights are merged into the latest phase.
Changes take effect on the next refresh.
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
key:
type: string
weight:
description: Traffic weight (0–1)
type: number
minimum: 0
maximum: 1
required:
- id
additionalProperties: false
coverage:
description: >-
Traffic coverage (0–1) for the latest phase. Used when
computing scaled impact.
type: number
minimum: 0
maximum: 1
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
report:
$ref: '#/components/schemas/Report'
required:
- report
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT 'https://api.growthbook.io/api/v1/reports/{id}/settings'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/namespaces:
get:
operationId: listNamespaces
summary: Get all namespaces
tags:
- namespaces
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
namespaces:
type: array
items:
$ref: '#/components/schemas/Namespace'
required:
- namespaces
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/namespaces' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: postNamespace
summary: Create a namespace
tags:
- namespaces
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
displayName:
description: >-
Human-readable display name. Must be unique within the
organization.
type: string
description:
description: Put context here, not in the name.
type: string
status:
type: string
enum:
- active
- inactive
format:
description: >-
Namespace format. Defaults to 'multiRange', which supports
multiple ranges per experiment and a configurable hash
attribute.
type: string
enum:
- legacy
- multiRange
hashAttribute:
description: >-
Required when format is 'multiRange'. The user attribute
(e.g. 'id', 'device_id') used to assign users to namespace
buckets.
type: string
required:
- displayName
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
namespace:
$ref: '#/components/schemas/Namespace'
required:
- namespace
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/namespaces' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"displayName":"Checkout Flow","description":"Experiments on the checkout funnel","format":"multiRange","hashAttribute":"id"}'
/v1/namespaces/{id}:
get:
operationId: getNamespace
summary: Get a single namespace
tags:
- namespaces
parameters:
- name: id
in: path
required: true
description: The unique id of the namespace
schema:
description: The unique id of the namespace
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
namespace:
$ref: '#/components/schemas/Namespace'
required:
- namespace
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET 'https://api.growthbook.io/api/v1/namespaces/ns-abc123'
\
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: putNamespace
summary: Update a namespace
tags:
- namespaces
parameters:
- name: id
in: path
required: true
description: The unique id of the namespace
schema:
description: The unique id of the namespace
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
displayName:
description: Human-readable display name.
type: string
description:
description: Namespace description.
type: string
status:
description: Set to 'inactive' to disable the namespace.
type: string
enum:
- active
- inactive
hashAttribute:
description: >-
Only applies to multiRange namespaces. Changes which user
attribute is used for bucket hashing going forward.
type: string
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
namespace:
$ref: '#/components/schemas/Namespace'
required:
- namespace
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT 'https://api.growthbook.io/api/v1/namespaces/ns-abc123'
\
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"displayName":"Checkout v2","status":"inactive"}'
delete:
operationId: deleteNamespace
summary: Delete a namespace
description: >-
Permanently removes a namespace from the organization. Returns a 409
error if any active experiments currently reference this namespace —
disable or remove those references first.
tags:
- namespaces
parameters:
- name: id
in: path
required: true
description: The unique id of the namespace
schema:
description: The unique id of the namespace
type: string
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
description: The ID of the deleted namespace.
example: ns-abc123
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/namespaces/ns-abc123' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/namespaces/{id}/memberships:
get:
operationId: getNamespaceMemberships
summary: Get namespace membership
tags:
- namespaces
parameters:
- name: id
in: path
required: true
description: The unique id of the namespace
schema:
description: The unique id of the namespace
type: string
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: Successful response
content:
application/json:
schema:
allOf:
- type: object
properties:
experiments:
type: array
items:
$ref: '#/components/schemas/NamespaceExperimentMember'
required:
- experiments
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/namespaces/ns-abc123/memberships'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/namespaces/{id}/rotateSeed:
post:
operationId: postNamespaceRotateSeed
summary: Rotate namespace seed
description: >-
⚠️ Dangerous: sets a new seed for a multiRange namespace. Every user's
bucket position within the namespace is re-computed immediately, which
re-randomizes traffic eligibility for **all** experiments currently
using this namespace. Only do this if you intentionally want to
reshuffle all allocations across experiments. This could be useful when
re-using a namespace for a new set of experiments.
tags:
- namespaces
parameters:
- name: id
in: path
required: true
description: The unique id of the namespace
schema:
description: The unique id of the namespace
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
seed:
description: >-
A specific value to use as the new seed. If omitted, a
random value is generated.
type: string
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
namespace:
$ref: '#/components/schemas/Namespace'
required:
- namespace
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/namespaces/ns-abc123/rotateSeed' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/transform-copy:
post:
operationId: postCopyTransform
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
visualChangesetId:
type: string
copy:
type: string
mode:
type: string
enum:
- energetic
- concise
- humorous
required:
- visualChangesetId
- copy
- mode
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema: {}
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/transform-copy' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/dashboards/{id}:
get:
operationId: getDashboard
summary: Get a single dashboard
tags:
- Dashboards
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
dashboard:
$ref: '#/components/schemas/Dashboard'
required:
- dashboard
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/dashboards/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteDashboard
summary: Delete a single dashboard
tags:
- Dashboards
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X DELETE 'https://api.growthbook.io/api/v1/dashboards/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: updateDashboard
summary: Update a single dashboard
tags:
- Dashboards
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
description: The display name of the Dashboard
type: string
editLevel:
description: >-
Dashboards that are "published" are editable by organization
members with appropriate permissions
type: string
enum:
- published
- private
shareLevel:
description: >-
General Dashboards only. Dashboards that are "published" are
viewable by organization members with appropriate
permissions
type: string
enum:
- published
- private
enableAutoUpdates:
description: >-
If enabled for a General Dashboard, also requires an
updateSchedule
type: boolean
updateSchedule:
description: >-
General Dashboards only. Experiment Dashboards update based
on the parent experiment instead
anyOf:
- type: object
properties:
type:
type: string
const: stale
hours:
type: number
required:
- type
- hours
additionalProperties: false
- type: object
properties:
type:
type: string
const: cron
cron:
type: string
required:
- type
- cron
additionalProperties: false
projects:
description: >-
General Dashboards only, Experiment Dashboards use the
experiment's projects
type: array
items:
type: string
globalControls:
type: object
properties:
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
projects:
type: array
items:
type: string
experimentSearchString:
type: string
additionalProperties: false
comparison:
description: >-
Dashboard-wide compare-to-previous-period. Takes precedence
over any per-block comparison.
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
blocks:
type: array
items:
anyOf:
- type: object
properties:
id:
type: string
minLength: 1
required:
- id
additionalProperties: false
- anyOf:
- type: object
properties:
type:
type: string
const: markdown
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
content:
type: string
id:
type: string
minLength: 1
uid:
type: string
organization:
type: string
required:
- type
- title
- description
- content
- id
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-metadata
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
showDescription:
type: boolean
showHypothesis:
type: boolean
showVariationImages:
type: boolean
variationIds:
type: array
items:
type: string
id:
type: string
minLength: 1
uid:
type: string
organization:
type: string
required:
- type
- title
- description
- experimentId
- showDescription
- showHypothesis
- showVariationImages
- id
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-metric
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
metricIds:
type: array
items:
type: string
variationIds:
type: array
items:
type: string
baselineRow:
type: number
differenceType:
type: string
enum:
- absolute
- relative
- scaled
columnsFilter:
type: array
items:
type: string
enum:
- Metric & Variation Names
- Baseline Average
- Variation Averages
- Chance to Win
- CI Graph
- Lift
sliceTagsFilter:
type: array
items:
type: string
metricTagFilter:
type: array
items:
type: string
sortBy:
anyOf:
- type: string
enum:
- metrics
- metricTags
- significance
- change
- type: 'null'
sortDirection:
anyOf:
- type: string
enum:
- asc
- desc
- type: 'null'
id:
type: string
minLength: 1
uid:
type: string
organization:
type: string
required:
- type
- title
- description
- snapshotId
- experimentId
- metricIds
- variationIds
- baselineRow
- differenceType
- columnsFilter
- sliceTagsFilter
- metricTagFilter
- sortBy
- sortDirection
- id
additionalProperties: false
- type: object
properties:
type:
type: string
const: metric-experiments
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
metricId:
type: string
projects:
type: array
items:
type: string
experimentSearchString:
type: string
differenceType:
type: string
enum:
- absolute
- relative
- scaled
bandits:
type: boolean
startDateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
endDateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
columns:
type: array
items:
type: object
properties:
id:
type: string
visible:
type: boolean
required:
- id
- visible
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
id:
type: string
minLength: 1
uid:
type: string
organization:
type: string
required:
- type
- title
- description
- metricId
- projects
- experimentSearchString
- differenceType
- bandits
- id
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiments-scaled-impact
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
projects:
type: array
items:
type: string
experimentSearchString:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
metricId:
type: string
id:
type: string
minLength: 1
uid:
type: string
organization:
type: string
required:
- type
- title
- description
- dateRange
- projects
- metricId
- id
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiments-win-rate
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
projects:
type: array
items:
type: string
experimentSearchString:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
showProjectBreakdown:
type: boolean
id:
type: string
minLength: 1
uid:
type: string
organization:
type: string
required:
- type
- title
- description
- dateRange
- projects
- showProjectBreakdown
- id
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiments-status
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
projects:
type: array
items:
type: string
experimentSearchString:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
id:
type: string
minLength: 1
uid:
type: string
organization:
type: string
required:
- type
- title
- description
- dateRange
- projects
- id
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-dimension
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
dimensionId:
type: string
dimensionValues:
type: array
items:
type: string
metricIds:
type: array
items:
type: string
variationIds:
type: array
items:
type: string
baselineRow:
type: number
differenceType:
type: string
enum:
- absolute
- relative
- scaled
columnsFilter:
type: array
items:
type: string
enum:
- Metric & Variation Names
- Baseline Average
- Variation Averages
- Chance to Win
- CI Graph
- Lift
metricTagFilter:
type: array
items:
type: string
sortBy:
anyOf:
- type: string
enum:
- metrics
- metricTags
- significance
- change
- type: 'null'
sortDirection:
anyOf:
- type: string
enum:
- asc
- desc
- type: 'null'
id:
type: string
minLength: 1
uid:
type: string
organization:
type: string
required:
- type
- title
- description
- snapshotId
- experimentId
- dimensionId
- dimensionValues
- metricIds
- variationIds
- baselineRow
- differenceType
- columnsFilter
- metricTagFilter
- sortBy
- sortDirection
- id
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-time-series
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
metricId:
type: string
metricIds:
type: array
items:
type: string
variationIds:
type: array
items:
type: string
differenceType:
type: string
enum:
- absolute
- relative
- scaled
sliceTagsFilter:
type: array
items:
type: string
metricTagFilter:
type: array
items:
type: string
sortBy:
anyOf:
- type: string
enum:
- metrics
- metricTags
- significance
- change
- type: 'null'
sortDirection:
anyOf:
- type: string
enum:
- asc
- desc
- type: 'null'
id:
type: string
minLength: 1
uid:
type: string
organization:
type: string
required:
- type
- title
- description
- snapshotId
- experimentId
- metricIds
- variationIds
- differenceType
- sliceTagsFilter
- metricTagFilter
- sortBy
- sortDirection
- id
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-traffic
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
showTable:
type: boolean
showTimeseries:
type: boolean
id:
type: string
minLength: 1
uid:
type: string
organization:
type: string
required:
- type
- title
- description
- experimentId
- showTable
- showTimeseries
- id
additionalProperties: false
- type: object
properties:
type:
type: string
const: sql-explorer
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
savedQueryId:
type: string
dataVizConfigIndex:
type: number
blockConfig:
type: array
items:
type: string
id:
type: string
minLength: 1
uid:
type: string
organization:
type: string
required:
- type
- title
- description
- savedQueryId
- blockConfig
- id
additionalProperties: false
- type: object
properties:
type:
type: string
const: metric-explorer
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
factMetricId:
type: string
visualizationType:
type: string
enum:
- histogram
- bigNumber
- timeseries
valueType:
type: string
enum:
- avg
- sum
metricAnalysisId:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonMetricAnalysisId:
type: string
analysisSettings:
type: object
properties:
userIdType:
type: string
lookbackDays:
type: number
populationType:
type: string
enum:
- metric
- factTable
- exposureQuery
- population
- segment
populationId:
anyOf:
- type: string
- type: 'null'
additionalNumeratorFilters:
type: array
items:
type: string
additionalDenominatorFilters:
type: array
items:
type: string
startDate:
type: string
endDate:
type: string
required:
- userIdType
- lookbackDays
- populationType
- populationId
- startDate
- endDate
additionalProperties: false
id:
type: string
minLength: 1
uid:
type: string
organization:
type: string
required:
- type
- title
- description
- factMetricId
- visualizationType
- valueType
- metricAnalysisId
- analysisSettings
- id
additionalProperties: false
- type: object
properties:
type:
type: string
const: metric-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: metric
dataset:
type: object
properties:
type:
type: string
const: metric
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: metric
metricId:
type: string
unit:
anyOf:
- type: string
- type: 'null'
denominatorUnit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- metricId
- unit
- denominatorUnit
additionalProperties: false
required:
- type
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit
it to send `config` alone and have the query
run when the dashboard is written.
type: string
id:
type: string
minLength: 1
uid:
type: string
organization:
type: string
required:
- type
- title
- description
- config
- id
additionalProperties: false
- type: object
properties:
type:
type: string
const: fact-table-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: fact_table
dataset:
type: object
properties:
type:
type: string
const: fact_table
factTableId:
anyOf:
- type: string
- type: 'null'
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: fact_table
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
required:
- type
- factTableId
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit
it to send `config` alone and have the query
run when the dashboard is written.
type: string
id:
type: string
minLength: 1
uid:
type: string
organization:
type: string
required:
- type
- title
- description
- config
- id
additionalProperties: false
- type: object
properties:
type:
type: string
const: data-source-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: data_source
dataset:
type: object
properties:
type:
type: string
const: data_source
table:
type: string
path:
type: string
timestampColumn:
type: string
columnTypes:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- string
- number
- date
- boolean
- other
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: data_source
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
required:
- type
- table
- path
- timestampColumn
- columnTypes
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit
it to send `config` alone and have the query
run when the dashboard is written.
type: string
id:
type: string
minLength: 1
uid:
type: string
organization:
type: string
required:
- type
- title
- description
- config
- id
additionalProperties: false
- type: object
properties:
type:
type: string
const: funnel-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: funnel
dataset:
type: object
properties:
type:
type: string
const: funnel
unit:
anyOf:
- type: string
- type: 'null'
steps:
maxItems: 20
type: array
items:
type: object
properties:
name:
type: string
factTableId:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
optional:
type: boolean
conversionWindow:
anyOf:
- type: object
properties:
unit:
type: string
enum:
- weeks
- days
- hours
- minutes
value:
type: number
exclusiveMinimum: 0
required:
- unit
- value
additionalProperties: false
- type: 'null'
required:
- name
- factTableId
- rowFilters
- optional
additionalProperties: false
concurrencyWindowSeconds:
type: integer
minimum: 0
yAxisScale:
type: string
enum:
- count
- percent
required:
- type
- unit
- steps
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
linkedFunnelMetricId:
anyOf:
- type: string
- type: 'null'
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit
it to send `config` alone and have the query
run when the dashboard is written.
type: string
id:
type: string
minLength: 1
uid:
type: string
organization:
type: string
required:
- type
- title
- description
- config
- id
additionalProperties: false
- type: object
properties:
type:
type: string
const: sql-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: sql
dataset:
type: object
properties:
type:
type: string
const: sql
sql:
type: string
timestampColumn:
anyOf:
- type: string
- type: 'null'
columnTypes:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- string
- number
- date
- boolean
- other
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: sql
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
hiddenColumns:
type: array
items:
type: string
required:
- type
- sql
- timestampColumn
- columnTypes
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit
it to send `config` alone and have the query
run when the dashboard is written.
type: string
id:
type: string
minLength: 1
uid:
type: string
organization:
type: string
required:
- type
- title
- description
- config
- id
additionalProperties: false
- anyOf:
- type: object
properties:
type:
type: string
const: markdown
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
content:
type: string
required:
- type
- title
- description
- content
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-metadata
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
showDescription:
type: boolean
showHypothesis:
type: boolean
showVariationImages:
type: boolean
variationIds:
type: array
items:
type: string
required:
- type
- title
- description
- experimentId
- showDescription
- showHypothesis
- showVariationImages
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-metric
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
metricIds:
type: array
items:
type: string
variationIds:
type: array
items:
type: string
baselineRow:
type: number
differenceType:
type: string
enum:
- absolute
- relative
- scaled
columnsFilter:
type: array
items:
type: string
enum:
- Metric & Variation Names
- Baseline Average
- Variation Averages
- Chance to Win
- CI Graph
- Lift
sliceTagsFilter:
type: array
items:
type: string
metricTagFilter:
type: array
items:
type: string
sortBy:
anyOf:
- type: string
enum:
- metrics
- metricTags
- significance
- change
- type: 'null'
sortDirection:
anyOf:
- type: string
enum:
- asc
- desc
- type: 'null'
required:
- type
- title
- description
- snapshotId
- experimentId
- metricIds
- variationIds
- baselineRow
- differenceType
- columnsFilter
- sliceTagsFilter
- metricTagFilter
- sortBy
- sortDirection
additionalProperties: false
- type: object
properties:
type:
type: string
const: metric-experiments
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
metricId:
type: string
projects:
type: array
items:
type: string
experimentSearchString:
type: string
differenceType:
type: string
enum:
- absolute
- relative
- scaled
bandits:
type: boolean
startDateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
endDateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
columns:
type: array
items:
type: object
properties:
id:
type: string
visible:
type: boolean
required:
- id
- visible
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
required:
- type
- title
- description
- metricId
- projects
- experimentSearchString
- differenceType
- bandits
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiments-scaled-impact
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
projects:
type: array
items:
type: string
experimentSearchString:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
metricId:
type: string
required:
- type
- title
- description
- dateRange
- projects
- metricId
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiments-win-rate
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
projects:
type: array
items:
type: string
experimentSearchString:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
showProjectBreakdown:
type: boolean
required:
- type
- title
- description
- dateRange
- projects
- showProjectBreakdown
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiments-status
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
projects:
type: array
items:
type: string
experimentSearchString:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- type
- title
- description
- dateRange
- projects
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-dimension
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
dimensionId:
type: string
dimensionValues:
type: array
items:
type: string
metricIds:
type: array
items:
type: string
variationIds:
type: array
items:
type: string
baselineRow:
type: number
differenceType:
type: string
enum:
- absolute
- relative
- scaled
columnsFilter:
type: array
items:
type: string
enum:
- Metric & Variation Names
- Baseline Average
- Variation Averages
- Chance to Win
- CI Graph
- Lift
metricTagFilter:
type: array
items:
type: string
sortBy:
anyOf:
- type: string
enum:
- metrics
- metricTags
- significance
- change
- type: 'null'
sortDirection:
anyOf:
- type: string
enum:
- asc
- desc
- type: 'null'
required:
- type
- title
- description
- snapshotId
- experimentId
- dimensionId
- dimensionValues
- metricIds
- variationIds
- baselineRow
- differenceType
- columnsFilter
- metricTagFilter
- sortBy
- sortDirection
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-time-series
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
metricId:
type: string
metricIds:
type: array
items:
type: string
variationIds:
type: array
items:
type: string
differenceType:
type: string
enum:
- absolute
- relative
- scaled
sliceTagsFilter:
type: array
items:
type: string
metricTagFilter:
type: array
items:
type: string
sortBy:
anyOf:
- type: string
enum:
- metrics
- metricTags
- significance
- change
- type: 'null'
sortDirection:
anyOf:
- type: string
enum:
- asc
- desc
- type: 'null'
required:
- type
- title
- description
- snapshotId
- experimentId
- metricIds
- variationIds
- differenceType
- sliceTagsFilter
- metricTagFilter
- sortBy
- sortDirection
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-traffic
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
showTable:
type: boolean
showTimeseries:
type: boolean
required:
- type
- title
- description
- experimentId
- showTable
- showTimeseries
additionalProperties: false
- type: object
properties:
type:
type: string
const: sql-explorer
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
savedQueryId:
type: string
dataVizConfigIndex:
type: number
blockConfig:
type: array
items:
type: string
required:
- type
- title
- description
- savedQueryId
- blockConfig
additionalProperties: false
- type: object
properties:
type:
type: string
const: metric-explorer
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
factMetricId:
type: string
visualizationType:
type: string
enum:
- histogram
- bigNumber
- timeseries
valueType:
type: string
enum:
- avg
- sum
metricAnalysisId:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonMetricAnalysisId:
type: string
analysisSettings:
type: object
properties:
userIdType:
type: string
lookbackDays:
type: number
populationType:
type: string
enum:
- metric
- factTable
- exposureQuery
- population
- segment
populationId:
anyOf:
- type: string
- type: 'null'
additionalNumeratorFilters:
type: array
items:
type: string
additionalDenominatorFilters:
type: array
items:
type: string
startDate:
type: string
endDate:
type: string
required:
- userIdType
- lookbackDays
- populationType
- populationId
- startDate
- endDate
additionalProperties: false
required:
- type
- title
- description
- factMetricId
- visualizationType
- valueType
- metricAnalysisId
- analysisSettings
additionalProperties: false
- type: object
properties:
type:
type: string
const: metric-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: metric
dataset:
type: object
properties:
type:
type: string
const: metric
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: metric
metricId:
type: string
unit:
anyOf:
- type: string
- type: 'null'
denominatorUnit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- metricId
- unit
- denominatorUnit
additionalProperties: false
required:
- type
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit
it to send `config` alone and have the query
run when the dashboard is written.
type: string
required:
- type
- title
- description
- config
additionalProperties: false
- type: object
properties:
type:
type: string
const: fact-table-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: fact_table
dataset:
type: object
properties:
type:
type: string
const: fact_table
factTableId:
anyOf:
- type: string
- type: 'null'
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: fact_table
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
required:
- type
- factTableId
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit
it to send `config` alone and have the query
run when the dashboard is written.
type: string
required:
- type
- title
- description
- config
additionalProperties: false
- type: object
properties:
type:
type: string
const: data-source-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: data_source
dataset:
type: object
properties:
type:
type: string
const: data_source
table:
type: string
path:
type: string
timestampColumn:
type: string
columnTypes:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- string
- number
- date
- boolean
- other
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: data_source
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
required:
- type
- table
- path
- timestampColumn
- columnTypes
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit
it to send `config` alone and have the query
run when the dashboard is written.
type: string
required:
- type
- title
- description
- config
additionalProperties: false
- type: object
properties:
type:
type: string
const: funnel-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: funnel
dataset:
type: object
properties:
type:
type: string
const: funnel
unit:
anyOf:
- type: string
- type: 'null'
steps:
maxItems: 20
type: array
items:
type: object
properties:
name:
type: string
factTableId:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
optional:
type: boolean
conversionWindow:
anyOf:
- type: object
properties:
unit:
type: string
enum:
- weeks
- days
- hours
- minutes
value:
type: number
exclusiveMinimum: 0
required:
- unit
- value
additionalProperties: false
- type: 'null'
required:
- name
- factTableId
- rowFilters
- optional
additionalProperties: false
concurrencyWindowSeconds:
type: integer
minimum: 0
yAxisScale:
type: string
enum:
- count
- percent
required:
- type
- unit
- steps
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
linkedFunnelMetricId:
anyOf:
- type: string
- type: 'null'
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit
it to send `config` alone and have the query
run when the dashboard is written.
type: string
required:
- type
- title
- description
- config
additionalProperties: false
- type: object
properties:
type:
type: string
const: sql-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: sql
dataset:
type: object
properties:
type:
type: string
const: sql
sql:
type: string
timestampColumn:
anyOf:
- type: string
- type: 'null'
columnTypes:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- string
- number
- date
- boolean
- other
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: sql
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
hiddenColumns:
type: array
items:
type: string
required:
- type
- sql
- timestampColumn
- columnTypes
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit
it to send `config` alone and have the query
run when the dashboard is written.
type: string
required:
- type
- title
- description
- config
additionalProperties: false
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. Omit
to leave the current owner unchanged.
type: string
minLength: 1
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
dashboard:
$ref: '#/components/schemas/Dashboard'
required:
- dashboard
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X PUT 'https://api.growthbook.io/api/v1/dashboards/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/dashboards:
post:
operationId: createDashboard
summary: Create a single dashboard
description: >-
**Deprecated.** Use [POST /v2/dashboards](#operation/createDashboardV2)
instead.
This endpoint does not accept an `owner` and always assigns the
dashboard to the authenticated user. A dashboard created with an
organization secret API key, which has no associated user, therefore has
no owner. The v2 endpoint accepts an `owner` (userId or email) and
requires one when authenticating with an organization secret API key.
deprecated: true
tags:
- Dashboards
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
description: The display name of the Dashboard
type: string
editLevel:
description: >-
Dashboards that are "published" are editable by organization
members with appropriate permissions
type: string
enum:
- published
- private
shareLevel:
description: >-
General Dashboards only. Dashboards that are "published" are
viewable by organization members with appropriate
permissions
type: string
enum:
- published
- private
enableAutoUpdates:
description: >-
If enabled for a General Dashboard, also requires an
updateSchedule
type: boolean
updateSchedule:
description: >-
General Dashboards only. Experiment Dashboards update based
on the parent experiment instead
anyOf:
- type: object
properties:
type:
type: string
const: stale
hours:
type: number
required:
- type
- hours
additionalProperties: false
- type: object
properties:
type:
type: string
const: cron
cron:
type: string
required:
- type
- cron
additionalProperties: false
experimentId:
description: >-
The parent experiment for an Experiment Dashboard, or
undefined for a general dashboard
type: string
projects:
description: >-
General Dashboards only, Experiment Dashboards use the
experiment's projects
type: array
items:
type: string
globalControls:
type: object
properties:
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
projects:
type: array
items:
type: string
experimentSearchString:
type: string
additionalProperties: false
comparison:
description: >-
Dashboard-wide compare-to-previous-period. Takes precedence
over any per-block comparison.
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
blocks:
type: array
items:
anyOf:
- type: object
properties:
type:
type: string
const: markdown
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
content:
type: string
required:
- type
- title
- description
- content
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-metadata
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
showDescription:
type: boolean
showHypothesis:
type: boolean
showVariationImages:
type: boolean
variationIds:
type: array
items:
type: string
required:
- type
- title
- description
- experimentId
- showDescription
- showHypothesis
- showVariationImages
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-metric
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
metricIds:
type: array
items:
type: string
variationIds:
type: array
items:
type: string
baselineRow:
type: number
differenceType:
type: string
enum:
- absolute
- relative
- scaled
columnsFilter:
type: array
items:
type: string
enum:
- Metric & Variation Names
- Baseline Average
- Variation Averages
- Chance to Win
- CI Graph
- Lift
sliceTagsFilter:
type: array
items:
type: string
metricTagFilter:
type: array
items:
type: string
sortBy:
anyOf:
- type: string
enum:
- metrics
- metricTags
- significance
- change
- type: 'null'
sortDirection:
anyOf:
- type: string
enum:
- asc
- desc
- type: 'null'
required:
- type
- title
- description
- snapshotId
- experimentId
- metricIds
- variationIds
- baselineRow
- differenceType
- columnsFilter
- sliceTagsFilter
- metricTagFilter
- sortBy
- sortDirection
additionalProperties: false
- type: object
properties:
type:
type: string
const: metric-experiments
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
metricId:
type: string
projects:
type: array
items:
type: string
experimentSearchString:
type: string
differenceType:
type: string
enum:
- absolute
- relative
- scaled
bandits:
type: boolean
startDateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
endDateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
columns:
type: array
items:
type: object
properties:
id:
type: string
visible:
type: boolean
required:
- id
- visible
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
required:
- type
- title
- description
- metricId
- projects
- experimentSearchString
- differenceType
- bandits
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiments-scaled-impact
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
projects:
type: array
items:
type: string
experimentSearchString:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
metricId:
type: string
required:
- type
- title
- description
- dateRange
- projects
- metricId
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiments-win-rate
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
projects:
type: array
items:
type: string
experimentSearchString:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
showProjectBreakdown:
type: boolean
required:
- type
- title
- description
- dateRange
- projects
- showProjectBreakdown
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiments-status
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
projects:
type: array
items:
type: string
experimentSearchString:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- type
- title
- description
- dateRange
- projects
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-dimension
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
dimensionId:
type: string
dimensionValues:
type: array
items:
type: string
metricIds:
type: array
items:
type: string
variationIds:
type: array
items:
type: string
baselineRow:
type: number
differenceType:
type: string
enum:
- absolute
- relative
- scaled
columnsFilter:
type: array
items:
type: string
enum:
- Metric & Variation Names
- Baseline Average
- Variation Averages
- Chance to Win
- CI Graph
- Lift
metricTagFilter:
type: array
items:
type: string
sortBy:
anyOf:
- type: string
enum:
- metrics
- metricTags
- significance
- change
- type: 'null'
sortDirection:
anyOf:
- type: string
enum:
- asc
- desc
- type: 'null'
required:
- type
- title
- description
- snapshotId
- experimentId
- dimensionId
- dimensionValues
- metricIds
- variationIds
- baselineRow
- differenceType
- columnsFilter
- metricTagFilter
- sortBy
- sortDirection
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-time-series
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
metricId:
type: string
metricIds:
type: array
items:
type: string
variationIds:
type: array
items:
type: string
differenceType:
type: string
enum:
- absolute
- relative
- scaled
sliceTagsFilter:
type: array
items:
type: string
metricTagFilter:
type: array
items:
type: string
sortBy:
anyOf:
- type: string
enum:
- metrics
- metricTags
- significance
- change
- type: 'null'
sortDirection:
anyOf:
- type: string
enum:
- asc
- desc
- type: 'null'
required:
- type
- title
- description
- snapshotId
- experimentId
- metricIds
- variationIds
- differenceType
- sliceTagsFilter
- metricTagFilter
- sortBy
- sortDirection
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-traffic
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
showTable:
type: boolean
showTimeseries:
type: boolean
required:
- type
- title
- description
- experimentId
- showTable
- showTimeseries
additionalProperties: false
- type: object
properties:
type:
type: string
const: sql-explorer
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
savedQueryId:
type: string
dataVizConfigIndex:
type: number
blockConfig:
type: array
items:
type: string
required:
- type
- title
- description
- savedQueryId
- blockConfig
additionalProperties: false
- type: object
properties:
type:
type: string
const: metric-explorer
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
factMetricId:
type: string
visualizationType:
type: string
enum:
- histogram
- bigNumber
- timeseries
valueType:
type: string
enum:
- avg
- sum
metricAnalysisId:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonMetricAnalysisId:
type: string
analysisSettings:
type: object
properties:
userIdType:
type: string
lookbackDays:
type: number
populationType:
type: string
enum:
- metric
- factTable
- exposureQuery
- population
- segment
populationId:
anyOf:
- type: string
- type: 'null'
additionalNumeratorFilters:
type: array
items:
type: string
additionalDenominatorFilters:
type: array
items:
type: string
startDate:
type: string
endDate:
type: string
required:
- userIdType
- lookbackDays
- populationType
- populationId
- startDate
- endDate
additionalProperties: false
required:
- type
- title
- description
- factMetricId
- visualizationType
- valueType
- metricAnalysisId
- analysisSettings
additionalProperties: false
- type: object
properties:
type:
type: string
const: metric-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: metric
dataset:
type: object
properties:
type:
type: string
const: metric
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: metric
metricId:
type: string
unit:
anyOf:
- type: string
- type: 'null'
denominatorUnit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- metricId
- unit
- denominatorUnit
additionalProperties: false
required:
- type
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit it to
send `config` alone and have the query run when
the dashboard is written.
type: string
required:
- type
- title
- description
- config
additionalProperties: false
- type: object
properties:
type:
type: string
const: fact-table-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: fact_table
dataset:
type: object
properties:
type:
type: string
const: fact_table
factTableId:
anyOf:
- type: string
- type: 'null'
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: fact_table
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
required:
- type
- factTableId
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit it to
send `config` alone and have the query run when
the dashboard is written.
type: string
required:
- type
- title
- description
- config
additionalProperties: false
- type: object
properties:
type:
type: string
const: data-source-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: data_source
dataset:
type: object
properties:
type:
type: string
const: data_source
table:
type: string
path:
type: string
timestampColumn:
type: string
columnTypes:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- string
- number
- date
- boolean
- other
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: data_source
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
required:
- type
- table
- path
- timestampColumn
- columnTypes
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit it to
send `config` alone and have the query run when
the dashboard is written.
type: string
required:
- type
- title
- description
- config
additionalProperties: false
- type: object
properties:
type:
type: string
const: funnel-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: funnel
dataset:
type: object
properties:
type:
type: string
const: funnel
unit:
anyOf:
- type: string
- type: 'null'
steps:
maxItems: 20
type: array
items:
type: object
properties:
name:
type: string
factTableId:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
optional:
type: boolean
conversionWindow:
anyOf:
- type: object
properties:
unit:
type: string
enum:
- weeks
- days
- hours
- minutes
value:
type: number
exclusiveMinimum: 0
required:
- unit
- value
additionalProperties: false
- type: 'null'
required:
- name
- factTableId
- rowFilters
- optional
additionalProperties: false
concurrencyWindowSeconds:
type: integer
minimum: 0
yAxisScale:
type: string
enum:
- count
- percent
required:
- type
- unit
- steps
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
linkedFunnelMetricId:
anyOf:
- type: string
- type: 'null'
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit it to
send `config` alone and have the query run when
the dashboard is written.
type: string
required:
- type
- title
- description
- config
additionalProperties: false
- type: object
properties:
type:
type: string
const: sql-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: sql
dataset:
type: object
properties:
type:
type: string
const: sql
sql:
type: string
timestampColumn:
anyOf:
- type: string
- type: 'null'
columnTypes:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- string
- number
- date
- boolean
- other
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: sql
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
hiddenColumns:
type: array
items:
type: string
required:
- type
- sql
- timestampColumn
- columnTypes
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit it to
send `config` alone and have the query run when
the dashboard is written.
type: string
required:
- type
- title
- description
- config
additionalProperties: false
required:
- title
- editLevel
- shareLevel
- enableAutoUpdates
- blocks
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
dashboard:
$ref: '#/components/schemas/Dashboard'
required:
- dashboard
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/dashboards' \
-H 'Authorization: Bearer YOUR_API_KEY'
get:
operationId: listDashboards
summary: Get all dashboards
tags:
- Dashboards
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
dashboards:
type: array
items:
$ref: '#/components/schemas/Dashboard'
required:
- dashboards
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/dashboards' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v2/dashboards:
post:
operationId: createDashboardV2
summary: Create a single dashboard
tags:
- Dashboards
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
description: The display name of the Dashboard
type: string
editLevel:
description: >-
Dashboards that are "published" are editable by organization
members with appropriate permissions
type: string
enum:
- published
- private
shareLevel:
description: >-
General Dashboards only. Dashboards that are "published" are
viewable by organization members with appropriate
permissions
type: string
enum:
- published
- private
enableAutoUpdates:
description: >-
If enabled for a General Dashboard, also requires an
updateSchedule
type: boolean
updateSchedule:
description: >-
General Dashboards only. Experiment Dashboards update based
on the parent experiment instead
anyOf:
- type: object
properties:
type:
type: string
const: stale
hours:
type: number
required:
- type
- hours
additionalProperties: false
- type: object
properties:
type:
type: string
const: cron
cron:
type: string
required:
- type
- cron
additionalProperties: false
experimentId:
description: >-
The parent experiment for an Experiment Dashboard, or
undefined for a general dashboard
type: string
projects:
description: >-
General Dashboards only, Experiment Dashboards use the
experiment's projects
type: array
items:
type: string
globalControls:
type: object
properties:
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
projects:
type: array
items:
type: string
experimentSearchString:
type: string
additionalProperties: false
comparison:
description: >-
Dashboard-wide compare-to-previous-period. Takes precedence
over any per-block comparison.
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
blocks:
type: array
items:
anyOf:
- type: object
properties:
type:
type: string
const: markdown
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
content:
type: string
required:
- type
- title
- description
- content
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-metadata
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
showDescription:
type: boolean
showHypothesis:
type: boolean
showVariationImages:
type: boolean
variationIds:
type: array
items:
type: string
required:
- type
- title
- description
- experimentId
- showDescription
- showHypothesis
- showVariationImages
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-metric
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
metricIds:
type: array
items:
type: string
variationIds:
type: array
items:
type: string
baselineRow:
type: number
differenceType:
type: string
enum:
- absolute
- relative
- scaled
columnsFilter:
type: array
items:
type: string
enum:
- Metric & Variation Names
- Baseline Average
- Variation Averages
- Chance to Win
- CI Graph
- Lift
sliceTagsFilter:
type: array
items:
type: string
metricTagFilter:
type: array
items:
type: string
sortBy:
anyOf:
- type: string
enum:
- metrics
- metricTags
- significance
- change
- type: 'null'
sortDirection:
anyOf:
- type: string
enum:
- asc
- desc
- type: 'null'
required:
- type
- title
- description
- snapshotId
- experimentId
- metricIds
- variationIds
- baselineRow
- differenceType
- columnsFilter
- sliceTagsFilter
- metricTagFilter
- sortBy
- sortDirection
additionalProperties: false
- type: object
properties:
type:
type: string
const: metric-experiments
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
metricId:
type: string
projects:
type: array
items:
type: string
experimentSearchString:
type: string
differenceType:
type: string
enum:
- absolute
- relative
- scaled
bandits:
type: boolean
startDateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
endDateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
columns:
type: array
items:
type: object
properties:
id:
type: string
visible:
type: boolean
required:
- id
- visible
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
required:
- type
- title
- description
- metricId
- projects
- experimentSearchString
- differenceType
- bandits
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiments-scaled-impact
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
projects:
type: array
items:
type: string
experimentSearchString:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
metricId:
type: string
required:
- type
- title
- description
- dateRange
- projects
- metricId
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiments-win-rate
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
projects:
type: array
items:
type: string
experimentSearchString:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
showProjectBreakdown:
type: boolean
required:
- type
- title
- description
- dateRange
- projects
- showProjectBreakdown
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiments-status
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
projects:
type: array
items:
type: string
experimentSearchString:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- type
- title
- description
- dateRange
- projects
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-dimension
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
dimensionId:
type: string
dimensionValues:
type: array
items:
type: string
metricIds:
type: array
items:
type: string
variationIds:
type: array
items:
type: string
baselineRow:
type: number
differenceType:
type: string
enum:
- absolute
- relative
- scaled
columnsFilter:
type: array
items:
type: string
enum:
- Metric & Variation Names
- Baseline Average
- Variation Averages
- Chance to Win
- CI Graph
- Lift
metricTagFilter:
type: array
items:
type: string
sortBy:
anyOf:
- type: string
enum:
- metrics
- metricTags
- significance
- change
- type: 'null'
sortDirection:
anyOf:
- type: string
enum:
- asc
- desc
- type: 'null'
required:
- type
- title
- description
- snapshotId
- experimentId
- dimensionId
- dimensionValues
- metricIds
- variationIds
- baselineRow
- differenceType
- columnsFilter
- metricTagFilter
- sortBy
- sortDirection
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-time-series
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
metricId:
type: string
metricIds:
type: array
items:
type: string
variationIds:
type: array
items:
type: string
differenceType:
type: string
enum:
- absolute
- relative
- scaled
sliceTagsFilter:
type: array
items:
type: string
metricTagFilter:
type: array
items:
type: string
sortBy:
anyOf:
- type: string
enum:
- metrics
- metricTags
- significance
- change
- type: 'null'
sortDirection:
anyOf:
- type: string
enum:
- asc
- desc
- type: 'null'
required:
- type
- title
- description
- snapshotId
- experimentId
- metricIds
- variationIds
- differenceType
- sliceTagsFilter
- metricTagFilter
- sortBy
- sortDirection
additionalProperties: false
- type: object
properties:
type:
type: string
const: experiment-traffic
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
showTable:
type: boolean
showTimeseries:
type: boolean
required:
- type
- title
- description
- experimentId
- showTable
- showTimeseries
additionalProperties: false
- type: object
properties:
type:
type: string
const: sql-explorer
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
savedQueryId:
type: string
dataVizConfigIndex:
type: number
blockConfig:
type: array
items:
type: string
required:
- type
- title
- description
- savedQueryId
- blockConfig
additionalProperties: false
- type: object
properties:
type:
type: string
const: metric-explorer
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
factMetricId:
type: string
visualizationType:
type: string
enum:
- histogram
- bigNumber
- timeseries
valueType:
type: string
enum:
- avg
- sum
metricAnalysisId:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonMetricAnalysisId:
type: string
analysisSettings:
type: object
properties:
userIdType:
type: string
lookbackDays:
type: number
populationType:
type: string
enum:
- metric
- factTable
- exposureQuery
- population
- segment
populationId:
anyOf:
- type: string
- type: 'null'
additionalNumeratorFilters:
type: array
items:
type: string
additionalDenominatorFilters:
type: array
items:
type: string
startDate:
type: string
endDate:
type: string
required:
- userIdType
- lookbackDays
- populationType
- populationId
- startDate
- endDate
additionalProperties: false
required:
- type
- title
- description
- factMetricId
- visualizationType
- valueType
- metricAnalysisId
- analysisSettings
additionalProperties: false
- type: object
properties:
type:
type: string
const: metric-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: metric
dataset:
type: object
properties:
type:
type: string
const: metric
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: metric
metricId:
type: string
unit:
anyOf:
- type: string
- type: 'null'
denominatorUnit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- metricId
- unit
- denominatorUnit
additionalProperties: false
required:
- type
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit it to
send `config` alone and have the query run when
the dashboard is written.
type: string
required:
- type
- title
- description
- config
additionalProperties: false
- type: object
properties:
type:
type: string
const: fact-table-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: fact_table
dataset:
type: object
properties:
type:
type: string
const: fact_table
factTableId:
anyOf:
- type: string
- type: 'null'
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: fact_table
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
required:
- type
- factTableId
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit it to
send `config` alone and have the query run when
the dashboard is written.
type: string
required:
- type
- title
- description
- config
additionalProperties: false
- type: object
properties:
type:
type: string
const: data-source-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: data_source
dataset:
type: object
properties:
type:
type: string
const: data_source
table:
type: string
path:
type: string
timestampColumn:
type: string
columnTypes:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- string
- number
- date
- boolean
- other
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: data_source
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
required:
- type
- table
- path
- timestampColumn
- columnTypes
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit it to
send `config` alone and have the query run when
the dashboard is written.
type: string
required:
- type
- title
- description
- config
additionalProperties: false
- type: object
properties:
type:
type: string
const: funnel-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: funnel
dataset:
type: object
properties:
type:
type: string
const: funnel
unit:
anyOf:
- type: string
- type: 'null'
steps:
maxItems: 20
type: array
items:
type: object
properties:
name:
type: string
factTableId:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
optional:
type: boolean
conversionWindow:
anyOf:
- type: object
properties:
unit:
type: string
enum:
- weeks
- days
- hours
- minutes
value:
type: number
exclusiveMinimum: 0
required:
- unit
- value
additionalProperties: false
- type: 'null'
required:
- name
- factTableId
- rowFilters
- optional
additionalProperties: false
concurrencyWindowSeconds:
type: integer
minimum: 0
yAxisScale:
type: string
enum:
- count
- percent
required:
- type
- unit
- steps
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
linkedFunnelMetricId:
anyOf:
- type: string
- type: 'null'
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit it to
send `config` alone and have the query run when
the dashboard is written.
type: string
required:
- type
- title
- description
- config
additionalProperties: false
- type: object
properties:
type:
type: string
const: sql-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: sql
dataset:
type: object
properties:
type:
type: string
const: sql
sql:
type: string
timestampColumn:
anyOf:
- type: string
- type: 'null'
columnTypes:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- string
- number
- date
- boolean
- other
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: sql
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
hiddenColumns:
type: array
items:
type: string
required:
- type
- sql
- timestampColumn
- columnTypes
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
explorerAnalysisId:
description: >-
The exploration run this block renders. Omit it to
send `config` alone and have the query run when
the dashboard is written.
type: string
required:
- type
- title
- description
- config
additionalProperties: false
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.
Optional when authenticating with a Personal Access Token
(PAT): when omitted, the owner defaults to the PAT's user.
Required when authenticating with an organization secret API
key (which has no associated user): omitting it fails with a
400. A private dashboard created with an organization secret
API key can only be retrieved or updated using its owner's
Personal Access Token (PAT).
type: string
minLength: 1
required:
- title
- editLevel
- shareLevel
- enableAutoUpdates
- blocks
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
dashboard:
$ref: '#/components/schemas/Dashboard'
required:
- dashboard
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v2/dashboards' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/dashboards/by-experiment/{experimentId}:
get:
operationId: getDashboardsForExperiment
summary: Get all dashboards for an experiment
tags:
- Dashboards
parameters:
- name: experimentId
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
dashboards:
type: array
items:
$ref: '#/components/schemas/Dashboard'
required:
- dashboards
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/dashboards/by-experiment/{experimentId}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/contextual-bandits/{id}:
get:
operationId: getContextualBandit
summary: Get a single contextualBandit
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
contextualBandit:
$ref: '#/components/schemas/ContextualBandit'
required:
- contextualBandit
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/contextual-bandits/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: updateContextualBandit
summary: Update a single contextualBandit
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description:
type: string
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
tags:
type: array
items:
type: string
trackingKey:
description: >-
Key sent with exposure events. Keep it short, in kebab-case.
Changing it after launch splits exposures across two keys.
type: string
hashAttribute:
type: string
datasource:
type: string
contextualBanditQueryId:
type: string
contextualAttributes:
type: array
items:
type: string
decisionMetric:
type: string
minUsersPerLeaf:
type: integer
exclusiveMinimum: 0
maxLeaves:
type: integer
exclusiveMinimum: 0
maximum: 12
priorSampleSize:
type: integer
minimum: 0
scheduleValue:
type: number
scheduleUnit:
type: string
enum:
- days
- hours
burnInValue:
type: number
burnInUnit:
type: string
enum:
- days
- hours
conversionWindowValue:
anyOf:
- type: number
- type: 'null'
conversionWindowUnit:
anyOf:
- type: string
enum:
- hours
- days
- type: 'null'
archived:
type: boolean
status:
type: string
enum:
- draft
- running
- stopped
coverage:
type: number
minimum: 0
maximum: 1
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
seed:
type: string
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
contextualBandit:
$ref: '#/components/schemas/ContextualBandit'
required:
- contextualBandit
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/contextual-bandits/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteContextualBandit
summary: Delete a single contextualBandit
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/contextual-bandits/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/contextual-bandits:
post:
operationId: createContextualBandit
summary: Create a single contextualBandit
tags:
- ContextualBandits
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name. Put details in `description`.
type: string
description:
description: Markdown. Put context here, not in the name.
type: string
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
tags:
description: >-
Tags for filtering and grouping. Use these instead of
encoding groups in names.
type: array
items:
type: string
trackingKey:
description: >-
Key sent with exposure events. Keep it short, in kebab-case.
Changing it after launch splits exposures across two keys.
type: string
hashAttribute:
type: string
decisionMetric:
type: string
variations:
type: array
items:
type: object
properties:
key:
description: >-
Key sent with exposure events (e.g. `0`, `1`).
Changing it after launch splits exposures.
type: string
name:
description: Short label shown in results (e.g. `Control`).
type: string
description:
description: What this variation changes.
type: string
required:
- key
- name
additionalProperties: false
datasource:
type: string
contextualBanditQueryId:
type: string
contextualAttributes:
type: array
items:
type: string
minUsersPerLeaf:
type: integer
exclusiveMinimum: 0
maxLeaves:
type: integer
exclusiveMinimum: 0
maximum: 12
priorSampleSize:
type: integer
minimum: 0
scheduleValue:
type: number
scheduleUnit:
type: string
enum:
- days
- hours
burnInValue:
type: number
burnInUnit:
type: string
enum:
- days
- hours
conversionWindowValue:
type: number
conversionWindowUnit:
type: string
enum:
- hours
- days
required:
- name
- trackingKey
- decisionMetric
- variations
- datasource
- contextualBanditQueryId
- contextualAttributes
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
contextualBandit:
$ref: '#/components/schemas/ContextualBandit'
required:
- contextualBandit
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/contextual-bandits' \
-H 'Authorization: Bearer YOUR_API_KEY'
get:
operationId: listContextualBandits
summary: Get all contextualBandits
tags:
- ContextualBandits
parameters:
- name: projectId
in: query
description: ''
schema:
type: string
- name: datasourceId
in: query
description: ''
schema:
type: string
- name: trackingKey
in: query
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
contextualBandits:
type: array
items:
$ref: '#/components/schemas/ContextualBandit'
required:
- contextualBandits
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/contextual-bandits' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/contextual-bandits/{id}/start:
post:
operationId: startContextualBandit
summary: Start a Contextual Bandit
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: The Contextual Bandit id
schema:
description: The Contextual Bandit id
type: string
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
contextualBandit:
$ref: '#/components/schemas/ContextualBandit'
required:
- contextualBandit
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/contextual-bandits/{id}/start' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/contextual-bandits/{id}/stop:
post:
operationId: stopContextualBandit
summary: Stop a Contextual Bandit
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: The Contextual Bandit id
schema:
description: The Contextual Bandit id
type: string
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
contextualBandit:
$ref: '#/components/schemas/ContextualBandit'
required:
- contextualBandit
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/contextual-bandits/{id}/stop' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/contextual-bandits/{id}/refresh:
post:
operationId: refreshContextualBandit
summary: Trigger a Contextual Bandit snapshot refresh
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: The Contextual Bandit id
schema:
description: The Contextual Bandit id
type: string
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
snapshotId:
type: string
cbeId:
type: string
required:
- snapshotId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/contextual-bandits/{id}/refresh' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/contextual-bandits/{id}/variations:
post:
operationId: updateContextualBanditVariations
summary: Add or remove Contextual Bandit variations
description: >-
Adds and/or removes variations on a Contextual Bandit. Send
`addVariations` and `removeVariationIds` independently; both are
optional. New arms must carry a `values` entry for each linked feature.
Running CBs publish the linked-feature updates; draft CBs stage them
until start. Under an approval flow, unapproved drafts leave the added
arm `pending` (zero weight, filtered from the SDK) until every linked
feature's draft is live. Removed arms are tombstoned; their ids can
never be re-added. Weights are reconciled server-side.
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
addVariations:
description: >-
New arms to add. Omit `id` to have the server generate one
and `key` to have the server assign the next integer.
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
maxLength: 10000
key:
type: string
screenshots:
type: array
items:
type: object
properties:
path:
type: string
width:
type: number
height:
type: number
description:
type: string
maxLength: 10000
required:
- path
additionalProperties: false
values:
description: >-
Value this new arm serves on each currently-linked
feature, keyed by feature id. Required for every
linked feature. Encode as a string for every
`valueType` (`"true"`, `"5"`, `"{\"a\":1}"`), matching
how `feature.defaultValue` is set.
type: object
propertyNames:
type: string
additionalProperties:
type: string
required:
- name
additionalProperties: false
removeVariationIds:
description: >-
Ids of active arms to remove. Removed arms are tombstoned in
place and their ids can never be re-added.
type: array
items:
type: string
updateVariations:
description: >-
Metadata edits to existing active arms. `name`,
`description`, and `key` may be changed; values, weights,
screenshots, and status are preserved.
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
key:
description: >-
New key for the arm. Must be unique across the
contextual bandit's arms, including removed ones. The
key is what SDKs report in exposure events, so
renaming an arm on a running bandit orphans exposures
already recorded under the old key.
type: string
required:
- id
additionalProperties: false
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
contextualBandit:
$ref: '#/components/schemas/ContextualBandit'
featureDraftPublishFailures:
type: array
items:
$ref: '#/components/schemas/featureDraftPublishFailures'
required:
- contextualBandit
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/contextual-bandits/{id}/variations'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/contextual-bandits/{id}/cancel:
post:
operationId: cancelContextualBandit
summary: Cancel a running Contextual Bandit snapshot refresh
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: The Contextual Bandit id
schema:
description: The Contextual Bandit id
type: string
responses:
'200':
description: Contextual Bandit snapshot refresh canceled
content:
application/json:
schema:
type: object
properties:
status:
type: number
required:
- status
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/contextual-bandits/{id}/cancel' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/contextual-bandits/{id}/visual-changesets:
post:
operationId: postContextualBanditVisualChangesets
summary: Create a visual changeset for a Contextual Bandit
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: The Contextual Bandit id
schema:
description: The Contextual Bandit id
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
editorUrl:
description: >-
URL of the page opened in the visual editor when creating
this changeset
type: string
urlPatterns:
description: >-
URL patterns that determine which pages this visual
changeset applies to
type: array
items:
type: object
properties:
include:
type: boolean
type:
type: string
enum:
- simple
- regex
pattern:
type: string
required:
- type
- pattern
additionalProperties: {}
required:
- editorUrl
- urlPatterns
additionalProperties: {}
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
visualChangeset:
$ref: '#/components/schemas/VisualChangeset'
required:
- visualChangeset
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/contextual-bandits/{id}/visual-changesets'
\
-H 'Authorization: Bearer YOUR_API_KEY'
get:
operationId: listContextualBanditVisualChangesets
summary: List visual changesets for a Contextual Bandit
tags:
- ContextualBandits
parameters:
- name: id
in: path
required: true
description: The Contextual Bandit id
schema:
description: The Contextual Bandit id
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
visualChangesets:
type: array
items:
$ref: '#/components/schemas/VisualChangeset'
required:
- visualChangesets
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/contextual-bandits/{id}/visual-changesets'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/contextual-bandit-queries/{id}:
get:
operationId: getContextualBanditQuery
summary: Get a single contextualBanditQuery
tags:
- ContextualBanditQueries
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
contextualBanditQuery:
$ref: '#/components/schemas/ContextualBanditQuery'
required:
- contextualBanditQuery
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/contextual-bandit-queries/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteContextualBanditQuery
summary: Delete a single contextualBanditQuery
tags:
- ContextualBanditQueries
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/contextual-bandit-queries/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: updateContextualBanditQuery
summary: Update a single contextualBanditQuery
tags:
- ContextualBanditQueries
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
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
name:
type: string
description:
type: string
userIdType:
type: string
query:
type: string
targetingAttributeColumns:
type: array
items:
type: string
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
contextualBanditQuery:
$ref: '#/components/schemas/ContextualBanditQuery'
required:
- contextualBanditQuery
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/contextual-bandit-queries/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/contextual-bandit-queries:
post:
operationId: createContextualBanditQuery
summary: Create a single contextualBanditQuery
tags:
- ContextualBanditQueries
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
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. When
omitted, it defaults to the requesting member: a personal
access token's owner, or the member an organization API key
assumes. An organization API key acting as itself leaves it
empty.
type: string
datasourceId:
type: string
name:
type: string
description:
type: string
userIdType:
type: string
query:
type: string
targetingAttributeColumns:
type: array
items:
type: string
required:
- datasourceId
- name
- userIdType
- query
- targetingAttributeColumns
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
contextualBanditQuery:
$ref: '#/components/schemas/ContextualBanditQuery'
required:
- contextualBanditQuery
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/contextual-bandit-queries' \
-H 'Authorization: Bearer YOUR_API_KEY'
get:
operationId: listContextualBanditQueries
summary: Get all contextualBanditQueries
tags:
- ContextualBanditQueries
parameters:
- name: datasourceId
in: query
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
contextualBanditQueries:
type: array
items:
$ref: '#/components/schemas/ContextualBanditQuery'
required:
- contextualBanditQueries
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/contextual-bandit-queries' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/interleavings/{id}:
get:
operationId: getInterleaving
summary: Get a single interleaving
tags:
- Interleavings
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
interleaving:
$ref: '#/components/schemas/Interleaving'
required:
- interleaving
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/interleavings/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: updateInterleaving
summary: Update a single interleaving
description: >-
Archive an interleaving experiment by setting `archived`. Use the start
and stop endpoints to change its status.
tags:
- Interleavings
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
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
tags:
type: array
items:
type: string
archived:
description: Stop a running interleaving experiment before archiving it.
type: boolean
trackingKey:
type: string
hashAttribute:
type: string
seed:
type: string
variations:
description: >-
Replaces both rankers. Each keeps its id by position, so the
first entry updates the first ranker.
type: array
prefixItems:
- type: object
properties:
key:
type: string
pattern: \S
name:
type: string
description:
type: string
maxLength: 10000
config:
description: >-
The ranker's config, as a JSON string. Passed to
`getList` in the SDK.
type: string
required:
- key
- name
- config
additionalProperties: false
- type: object
properties:
key:
type: string
pattern: \S
name:
type: string
description:
type: string
maxLength: 10000
config:
description: >-
The ranker's config, as a JSON string. Passed to
`getList` in the SDK.
type: string
required:
- key
- name
- config
additionalProperties: false
jsonSchema:
anyOf:
- description: >-
Validation schema to stage on the draft. The server sets
`date`, so don't send it.
type: object
properties:
schemaType:
type: string
enum:
- schema
- simple
schema:
type: string
simple:
type: object
properties:
type:
type: string
enum:
- object
- object[]
- primitive
- primitive[]
fields:
type: array
items:
type: object
properties:
key:
type: string
maxLength: 64
type:
type: string
enum:
- integer
- float
- string
- boolean
required:
type: boolean
default:
type: string
maxLength: 256
description:
type: string
maxLength: 10000
enum:
maxItems: 256
type: array
items:
type: string
maxLength: 256
min:
type: number
max:
type: number
nullable:
type: boolean
jsonSchema:
type: string
required:
- key
- type
- required
- default
- description
- enum
additionalProperties: false
additionalProperties:
type: boolean
invariants:
type: array
items:
type: object
properties:
name:
type: string
maxLength: 128
rule:
type: string
message:
type: string
maxLength: 10000
required:
- name
- rule
- message
additionalProperties: false
required:
- type
- fields
additionalProperties: false
enabled:
type: boolean
required:
- schemaType
- schema
- simple
- enabled
additionalProperties: false
- type: 'null'
datasource:
type: string
interleavingQueryId:
type: string
userIdType:
type: string
metrics:
type: array
items:
type: object
properties:
id:
type: string
analyses:
minItems: 1
type: array
items:
anyOf:
- type: object
properties:
type:
type: string
const: paired
required:
- type
additionalProperties: false
- type: object
properties:
type:
type: string
const: ownership
attribution:
type: string
enum:
- exposureCount
- engagementSignal
required:
- type
- attribution
additionalProperties: false
required:
- id
- analyses
additionalProperties: false
coverage:
type: number
minimum: 0
maximum: 1
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
environmentSettings:
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
enabled:
type: boolean
required:
- enabled
additionalProperties: false
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
interleaving:
$ref: '#/components/schemas/Interleaving'
required:
- interleaving
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X PUT 'https://api.growthbook.io/api/v1/interleavings/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/interleavings:
post:
operationId: createInterleaving
summary: Create a single interleaving
tags:
- Interleavings
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
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
tags:
type: array
items:
type: string
key:
description: >-
The key your code passes to `interleave()` as `key`. Can't
be changed later. Several experiments may share a key so you
can iterate without changing code, but only one of them can
be running in a given environment, and each needs its own
`trackingKey`.
type: string
pattern: ^[a-zA-Z0-9_.:\|\-]+$
trackingKey:
description: >-
The `experiment_id` recorded in exposures. Defaults to
`key`.
type: string
hashAttribute:
type: string
variations:
description: >-
Exactly two rankers. Users who are not exposed to
interleaved rankings get the first ranker's list.
type: array
prefixItems:
- type: object
properties:
key:
type: string
pattern: \S
name:
type: string
description:
type: string
maxLength: 10000
config:
description: >-
The ranker's config, as a JSON string. Passed to
`getList` in the SDK.
type: string
required:
- key
- name
- config
additionalProperties: false
- type: object
properties:
key:
type: string
pattern: \S
name:
type: string
description:
type: string
maxLength: 10000
config:
description: >-
The ranker's config, as a JSON string. Passed to
`getList` in the SDK.
type: string
required:
- key
- name
- config
additionalProperties: false
jsonSchema:
description: >-
Validation schema to stage on the draft. The server sets
`date`, so don't send it.
type: object
properties:
schemaType:
type: string
enum:
- schema
- simple
schema:
type: string
simple:
type: object
properties:
type:
type: string
enum:
- object
- object[]
- primitive
- primitive[]
fields:
type: array
items:
type: object
properties:
key:
type: string
maxLength: 64
type:
type: string
enum:
- integer
- float
- string
- boolean
required:
type: boolean
default:
type: string
maxLength: 256
description:
type: string
maxLength: 10000
enum:
maxItems: 256
type: array
items:
type: string
maxLength: 256
min:
type: number
max:
type: number
nullable:
type: boolean
jsonSchema:
type: string
required:
- key
- type
- required
- default
- description
- enum
additionalProperties: false
additionalProperties:
type: boolean
invariants:
type: array
items:
type: object
properties:
name:
type: string
maxLength: 128
rule:
type: string
message:
type: string
maxLength: 10000
required:
- name
- rule
- message
additionalProperties: false
required:
- type
- fields
additionalProperties: false
enabled:
type: boolean
required:
- schemaType
- schema
- simple
- enabled
additionalProperties: false
datasource:
type: string
interleavingQueryId:
type: string
userIdType:
type: string
metrics:
type: array
items:
type: object
properties:
id:
type: string
analyses:
minItems: 1
type: array
items:
anyOf:
- type: object
properties:
type:
type: string
const: paired
required:
- type
additionalProperties: false
- type: object
properties:
type:
type: string
const: ownership
attribution:
type: string
enum:
- exposureCount
- engagementSignal
required:
- type
- attribution
additionalProperties: false
required:
- id
- analyses
additionalProperties: false
coverage:
type: number
minimum: 0
maximum: 1
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
environmentSettings:
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
enabled:
type: boolean
required:
- enabled
additionalProperties: false
required:
- name
- key
- variations
- datasource
- interleavingQueryId
- userIdType
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
interleaving:
$ref: '#/components/schemas/Interleaving'
required:
- interleaving
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/interleavings' \
-H 'Authorization: Bearer YOUR_API_KEY'
get:
operationId: listInterleavings
summary: Get all interleavings
tags:
- Interleavings
parameters:
- name: projectId
in: query
description: ''
schema:
type: string
- name: datasourceId
in: query
description: ''
schema:
type: string
- name: trackingKey
in: query
description: ''
schema:
type: string
- name: key
in: query
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
interleavings:
type: array
items:
$ref: '#/components/schemas/Interleaving'
required:
- interleavings
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/interleavings' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/interleavings/{id}/start:
post:
operationId: startInterleaving
summary: Start an interleaving experiment
description: >-
Starts serving the interleaving to SDKs in its enabled environments. A
stopped interleaving can be started again; its start date is kept.
tags:
- Interleavings
parameters:
- name: id
in: path
required: true
description: The interleaving experiment id
schema:
description: The interleaving experiment id
type: string
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
interleaving:
$ref: '#/components/schemas/Interleaving'
required:
- interleaving
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/interleavings/{id}/start' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/interleavings/{id}/stop:
post:
operationId: stopInterleaving
summary: Stop an interleaving experiment
description: >-
Removes the interleaving from SDK payloads, so `interleave()` falls back
to `fallbackConfig`.
tags:
- Interleavings
parameters:
- name: id
in: path
required: true
description: The interleaving experiment id
schema:
description: The interleaving experiment id
type: string
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
interleaving:
$ref: '#/components/schemas/Interleaving'
required:
- interleaving
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/interleavings/{id}/stop' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/custom-fields:
post:
operationId: createCustomField
summary: Create a single customField
tags:
- CustomFields
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
description: >-
Unique, permanent key used in API payloads (e.g.
`jira_ticket`). Lowercase letters, numbers, hyphens, and
underscores. Put the label in `name`.
type: string
minLength: 1
name:
description: The display name of the custom field
type: string
description:
description: Help text shown under the field.
type: string
placeholder:
type: string
defaultValue:
anyOf:
- type: string
- type: number
- type: boolean
- type: string
format: date-time
- type: string
format: date
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
- type: array
items:
type: string
- type: array
items:
type: number
- type: array
items:
type: boolean
- type: array
items:
type: string
format: date-time
- type: array
items:
type: string
format: date
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
type:
description: The type of value this custom field will take
type: string
enum:
- text
- textarea
- markdown
- enum
- multiselect
- url
- number
- boolean
- date
- datetime
values:
type: string
creatable:
description: >-
For enum and multiselect fields, allow users to enter values
beyond the predefined list
type: boolean
required:
type: boolean
projects:
type: array
items:
type: string
sections:
description: >-
What types of objects this custom field is applicable to
(feature, experiment, attribute)
type: array
items:
type: string
enum:
- feature
- experiment
- attribute
required:
- id
- name
- type
- required
- sections
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
customField:
$ref: '#/components/schemas/CustomField'
required:
- customField
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/custom-fields' \
-H 'Authorization: Bearer YOUR_API_KEY'
get:
operationId: listCustomFields
summary: Get all custom fields
tags:
- CustomFields
parameters:
- name: projectId
in: query
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CustomField'
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/custom-fields' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/custom-fields/{id}:
delete:
operationId: deleteCustomField
summary: Delete a single customField
tags:
- CustomFields
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/index'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE 'https://api.growthbook.io/api/v1/custom-fields/{id}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
get:
operationId: getCustomField
summary: Get a single customField
tags:
- CustomFields
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
customField:
$ref: '#/components/schemas/CustomField'
required:
- customField
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/custom-fields/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: updateCustomField
summary: Update a single customField
tags:
- CustomFields
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: The display name of the custom field
type: string
description:
description: Help text shown under the field.
type: string
placeholder:
type: string
defaultValue:
anyOf:
- type: string
- type: number
- type: boolean
- type: string
format: date-time
- type: string
format: date
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
- type: array
items:
type: string
- type: array
items:
type: number
- type: array
items:
type: boolean
- type: array
items:
type: string
format: date-time
- type: array
items:
type: string
format: date
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
values:
type: string
creatable:
description: >-
For enum and multiselect fields, allow users to enter values
beyond the predefined list
type: boolean
required:
type: boolean
projects:
type: array
items:
type: string
sections:
description: >-
What types of objects this custom field is applicable to
(feature, experiment, attribute)
type: array
items:
type: string
enum:
- feature
- experiment
- attribute
active:
type: boolean
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
customField:
$ref: '#/components/schemas/CustomField'
required:
- customField
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X PUT 'https://api.growthbook.io/api/v1/custom-fields/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/metric-groups/{id}:
get:
operationId: getMetricGroup
summary: Get a single metricGroup
tags:
- MetricGroups
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
metricGroup:
$ref: '#/components/schemas/MetricGroup'
required:
- metricGroup
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/metric-groups/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteMetricGroup
summary: Delete a single metricGroup
tags:
- MetricGroups
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE 'https://api.growthbook.io/api/v1/metric-groups/{id}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: updateMetricGroup
summary: Update a single metricGroup
tags:
- MetricGroups
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name. Put details in `description`.
type: string
description:
description: Put context here, not in the name.
type: string
maxLength: 10000
tags:
description: >-
Tags for filtering and grouping. Use these instead of
encoding groups in names.
type: array
items:
type: string
projects:
description: >-
Project IDs that can use this. An empty list means all
Projects. Projects control access and availability, so don't
use them as labels.
type: array
items:
type: string
metrics:
type: array
items:
type: string
datasource:
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
archived:
type: boolean
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
metricGroup:
$ref: '#/components/schemas/MetricGroup'
required:
- metricGroup
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X PUT 'https://api.growthbook.io/api/v1/metric-groups/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/metric-groups:
post:
operationId: createMetricGroup
summary: Create a single metricGroup
tags:
- MetricGroups
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name. Put details in `description`.
type: string
description:
description: Put context here, not in the name.
type: string
maxLength: 10000
tags:
description: >-
Tags for filtering and grouping. Use these instead of
encoding groups in names.
type: array
items:
type: string
projects:
description: >-
Project IDs that can use this. An empty list means all
Projects. Projects control access and availability, so don't
use them as labels.
type: array
items:
type: string
metrics:
type: array
items:
type: string
datasource:
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
archived:
type: boolean
required:
- name
- description
- projects
- metrics
- datasource
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
metricGroup:
$ref: '#/components/schemas/MetricGroup'
required:
- metricGroup
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/metric-groups' \
-H 'Authorization: Bearer YOUR_API_KEY'
get:
operationId: listMetricGroups
summary: Get all metricGroups
tags:
- MetricGroups
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
metricGroups:
type: array
items:
$ref: '#/components/schemas/MetricGroup'
required:
- metricGroups
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/metric-groups' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/teams/{id}:
get:
operationId: getTeam
summary: Get a single team
tags:
- Teams
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
team:
$ref: '#/components/schemas/Team'
required:
- team
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/teams/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: updateTeam
summary: Update a single team
tags:
- Teams
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name. Put details in `description`.
type: string
createdBy:
type: string
description:
description: Put context here, not in the name.
type: string
role:
description: The global role for members of this team
type: string
limitAccessByEnvironment:
type: boolean
environments:
description: An empty array means 'all environments'
type: array
items:
type: string
projectRoles:
type: array
items:
type: object
properties:
role:
type: string
limitAccessByEnvironment:
type: boolean
environments:
type: array
items:
type: string
teams:
type: array
items:
type: string
additionalRoles:
type: array
items:
type: object
properties:
role:
type: string
limitAccessByEnvironment:
type: boolean
environments:
type: array
items:
type: string
required:
- role
- limitAccessByEnvironment
- environments
additionalProperties: false
project:
type: string
required:
- role
- limitAccessByEnvironment
- environments
- project
additionalProperties: false
managedBy:
anyOf:
- type: object
properties:
type:
type: string
const: vercel
resourceId:
type: string
required:
- type
- resourceId
additionalProperties: false
defaultProject:
type: string
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
team:
$ref: '#/components/schemas/Team'
required:
- team
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X PUT 'https://api.growthbook.io/api/v1/teams/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteTeam
summary: Delete a single team
tags:
- Teams
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/deleteMembers'
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X DELETE 'https://api.growthbook.io/api/v1/teams/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/teams:
post:
operationId: createTeam
summary: Create a single team
tags:
- Teams
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name. Put details in `description`.
type: string
createdBy:
type: string
description:
description: Put context here, not in the name.
type: string
role:
description: The global role for members of this team
type: string
limitAccessByEnvironment:
type: boolean
environments:
description: An empty array means 'all environments'
type: array
items:
type: string
projectRoles:
type: array
items:
type: object
properties:
role:
type: string
limitAccessByEnvironment:
type: boolean
environments:
type: array
items:
type: string
teams:
type: array
items:
type: string
additionalRoles:
type: array
items:
type: object
properties:
role:
type: string
limitAccessByEnvironment:
type: boolean
environments:
type: array
items:
type: string
required:
- role
- limitAccessByEnvironment
- environments
additionalProperties: false
project:
type: string
required:
- role
- limitAccessByEnvironment
- environments
- project
additionalProperties: false
managedBy:
anyOf:
- type: object
properties:
type:
type: string
const: vercel
resourceId:
type: string
required:
- type
- resourceId
additionalProperties: false
defaultProject:
type: string
required:
- name
- description
- role
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
team:
$ref: '#/components/schemas/Team'
required:
- team
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/teams' \
-H 'Authorization: Bearer YOUR_API_KEY'
get:
operationId: listTeams
summary: Get all teams
tags:
- Teams
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
teams:
type: array
items:
$ref: '#/components/schemas/Team'
required:
- teams
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/teams' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/teams/{id}/members:
post:
operationId: addTeamMembers
summary: Add members to team
tags:
- Teams
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
members:
type: array
items:
type: string
required:
- members
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
status:
type: number
required:
- status
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/teams/{id}/members' \
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: removeTeamMember
summary: Remove members from team
tags:
- Teams
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
members:
type: array
items:
type: string
required:
- members
additionalProperties: false
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
status:
type: number
required:
- status
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE 'https://api.growthbook.io/api/v1/teams/{id}/members'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/experiment-templates/{id}:
get:
operationId: getExperimentTemplate
summary: Get a single experimentTemplate
tags:
- ExperimentTemplates
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
experimentTemplate:
$ref: '#/components/schemas/ExperimentTemplate'
required:
- experimentTemplate
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/experiment-templates/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteExperimentTemplate
summary: Delete a single experimentTemplate
tags:
- ExperimentTemplates
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/experiment-templates/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: updateExperimentTemplate
summary: Update a single experimentTemplate
tags:
- ExperimentTemplates
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
project:
type: string
templateMetadata:
type: object
properties:
name:
description: Short display name (e.g. `Checkout test`).
type: string
description:
description: When to use this template.
type: string
maxLength: 10000
required:
- name
additionalProperties: false
type:
type: string
enum:
- standard
hypothesis:
description: >-
Default hypothesis for experiments created from this
template. Markdown. If we change X, metric Y will move
because Z.
type: string
description:
description: >-
Default description for experiments created from this
template. Markdown.
type: string
maxLength: 10000
tags:
description: >-
Tags for filtering and grouping. Use these instead of
encoding groups in names.
type: array
items:
type: string
customFields:
type: object
propertyNames:
type: string
additionalProperties:
type: string
datasource:
type: string
exposureQuery:
description: >-
The assignment query, grouping its ID with the identifier
type analyzed on. Mutually exclusive with the deprecated
`exposureQueryId`.
type: object
properties:
id:
description: The ID of one of the data source's assignment queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the query must
declare. Required when selecting a different assignment
query that declares several. Otherwise defaults to the
current identifier type, or the query's only one. Null
is treated as omitted, so a response's value can be sent
back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
exposureQueryId:
deprecated: true
description: >-
Deprecated: use `exposureQuery`. Rejected when selecting a
different assignment query that declares several identifier
types; set `exposureQuery.identifierType` instead.
type: string
hashAttribute:
type: string
fallbackAttribute:
type: string
disableStickyBucketing:
type: boolean
goalMetrics:
type: array
items:
type: string
secondaryMetrics:
type: array
items:
type: string
guardrailMetrics:
type: array
items:
type: string
activationMetric:
type: string
statsEngine:
type: string
enum:
- bayesian
- frequentist
segment:
type: string
skipPartialData:
type: boolean
targeting:
type: object
properties:
coverage:
type: number
minimum: 0
maximum: 1
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
condition:
type: string
required:
- coverage
- condition
additionalProperties: false
customMetricSlices:
type: array
items:
type: object
properties:
slices:
type: array
items:
type: object
properties:
column:
type: string
levels:
type: array
items:
type: string
required:
- column
- levels
additionalProperties: false
required:
- slices
additionalProperties: false
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
experimentTemplate:
$ref: '#/components/schemas/ExperimentTemplate'
required:
- experimentTemplate
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/experiment-templates/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/experiment-templates:
post:
operationId: createExperimentTemplate
summary: Create a single experimentTemplate
tags:
- ExperimentTemplates
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
project:
type: string
templateMetadata:
type: object
properties:
name:
description: Short display name (e.g. `Checkout test`).
type: string
description:
description: When to use this template.
type: string
maxLength: 10000
required:
- name
additionalProperties: false
type:
type: string
enum:
- standard
hypothesis:
description: >-
Default hypothesis for experiments created from this
template. Markdown. If we change X, metric Y will move
because Z.
type: string
description:
description: >-
Default description for experiments created from this
template. Markdown.
type: string
maxLength: 10000
tags:
description: >-
Tags for filtering and grouping. Use these instead of
encoding groups in names.
type: array
items:
type: string
customFields:
type: object
propertyNames:
type: string
additionalProperties:
type: string
datasource:
type: string
exposureQuery:
description: >-
The assignment query, grouping its ID with the identifier
type analyzed on. Mutually exclusive with the deprecated
`exposureQueryId`.
type: object
properties:
id:
description: The ID of one of the data source's assignment queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the query must
declare. Required when selecting a different assignment
query that declares several. Otherwise defaults to the
current identifier type, or the query's only one. Null
is treated as omitted, so a response's value can be sent
back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
exposureQueryId:
deprecated: true
description: >-
Deprecated: use `exposureQuery`. Rejected when selecting a
different assignment query that declares several identifier
types; set `exposureQuery.identifierType` instead.
type: string
hashAttribute:
type: string
fallbackAttribute:
type: string
disableStickyBucketing:
type: boolean
goalMetrics:
type: array
items:
type: string
secondaryMetrics:
type: array
items:
type: string
guardrailMetrics:
type: array
items:
type: string
activationMetric:
type: string
statsEngine:
type: string
enum:
- bayesian
- frequentist
segment:
type: string
skipPartialData:
type: boolean
targeting:
type: object
properties:
coverage:
type: number
minimum: 0
maximum: 1
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
condition:
type: string
required:
- coverage
- condition
additionalProperties: false
customMetricSlices:
type: array
items:
type: object
properties:
slices:
type: array
items:
type: object
properties:
column:
type: string
levels:
type: array
items:
type: string
required:
- column
- levels
additionalProperties: false
required:
- slices
additionalProperties: false
required:
- templateMetadata
- type
- datasource
- statsEngine
- targeting
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
experimentTemplate:
$ref: '#/components/schemas/ExperimentTemplate'
required:
- experimentTemplate
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST 'https://api.growthbook.io/api/v1/experiment-templates'
\
-H 'Authorization: Bearer YOUR_API_KEY'
get:
operationId: listExperimentTemplates
summary: Get all experimentTemplates
tags:
- ExperimentTemplates
parameters:
- name: projectId
in: query
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
experimentTemplates:
type: array
items:
$ref: '#/components/schemas/ExperimentTemplate'
required:
- experimentTemplates
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET 'https://api.growthbook.io/api/v1/experiment-templates'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/experiment-templates/bulk-import:
post:
operationId: bulkImportExperimentTemplates
summary: Bulk create or update experiment templates
tags:
- ExperimentTemplates
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
templates:
type: array
items:
type: object
properties:
id:
type: string
data:
type: object
properties:
project:
type: string
templateMetadata:
type: object
properties:
name:
description: Short display name (e.g. `Checkout test`).
type: string
description:
description: When to use this template.
type: string
maxLength: 10000
required:
- name
additionalProperties: false
type:
type: string
enum:
- standard
hypothesis:
description: >-
Default hypothesis for experiments created from
this template. Markdown. If we change X, metric Y
will move because Z.
type: string
description:
description: >-
Default description for experiments created from
this template. Markdown.
type: string
maxLength: 10000
tags:
description: >-
Tags for filtering and grouping. Use these instead
of encoding groups in names.
type: array
items:
type: string
customFields:
type: object
propertyNames:
type: string
additionalProperties:
type: string
datasource:
type: string
exposureQuery:
description: >-
The assignment query, grouping its ID with the
identifier type analyzed on. Mutually exclusive
with the deprecated `exposureQueryId`.
type: object
properties:
id:
description: >-
The ID of one of the data source's assignment
queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the
query must declare. Required when selecting a
different assignment query that declares
several. Otherwise defaults to the current
identifier type, or the query's only one. Null
is treated as omitted, so a response's value
can be sent back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
exposureQueryId:
deprecated: true
description: >-
Deprecated: use `exposureQuery`. Rejected when
selecting a different assignment query that
declares several identifier types; set
`exposureQuery.identifierType` instead.
type: string
hashAttribute:
type: string
fallbackAttribute:
type: string
disableStickyBucketing:
type: boolean
goalMetrics:
type: array
items:
type: string
secondaryMetrics:
type: array
items:
type: string
guardrailMetrics:
type: array
items:
type: string
activationMetric:
type: string
statsEngine:
type: string
enum:
- bayesian
- frequentist
segment:
type: string
skipPartialData:
type: boolean
targeting:
type: object
properties:
coverage:
type: number
minimum: 0
maximum: 1
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
condition:
type: string
required:
- coverage
- condition
additionalProperties: false
customMetricSlices:
type: array
items:
type: object
properties:
slices:
type: array
items:
type: object
properties:
column:
type: string
levels:
type: array
items:
type: string
required:
- column
- levels
additionalProperties: false
required:
- slices
additionalProperties: false
required:
- templateMetadata
- type
- datasource
- statsEngine
- targeting
additionalProperties: false
required:
- id
- data
additionalProperties: false
required:
- templates
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
added:
type: integer
updated:
type: integer
required:
- added
- updated
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/experiment-templates/bulk-import'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/product-analytics/metric-exploration:
post:
operationId: postMetricExploration
summary: Create a Metric based visualization
tags:
- AnalyticsExplorations
parameters:
- $ref: '#/components/parameters/cache'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: metric
dataset:
type: object
properties:
type:
type: string
const: metric
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: metric
metricId:
type: string
unit:
anyOf:
- type: string
- type: 'null'
denominatorUnit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- metricId
- unit
- denominatorUnit
additionalProperties: false
required:
- type
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
exploration:
anyOf:
- type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
datasource:
type: string
status:
type: string
enum:
- running
- success
- error
dateStart:
type: string
dateEnd:
type: string
error:
anyOf:
- type: string
- type: 'null'
result:
type: object
properties:
rows:
type: array
items:
type: object
properties:
dimensions:
type: array
items:
anyOf:
- type: string
- type: 'null'
values:
type: array
items:
type: object
properties:
metricId:
type: string
numerator:
anyOf:
- type: number
- type: 'null'
denominator:
anyOf:
- type: number
- type: 'null'
required:
- metricId
- numerator
- denominator
additionalProperties: false
steps:
type: array
items:
type: object
properties:
count:
type: number
timeFromPrevSumHrs:
anyOf:
- type: number
- type: 'null'
timeFromPrevSumSquaresHrs:
anyOf:
- type: number
- type: 'null'
required:
- count
- timeFromPrevSumHrs
- timeFromPrevSumSquaresHrs
additionalProperties: false
journey:
anyOf:
- type: object
properties:
kind:
type: string
const: path
direction:
type: string
enum:
- forward
- backward
levels:
type: array
items:
type: string
count:
type: number
required:
- kind
- direction
- levels
- count
additionalProperties: false
- type: object
properties:
kind:
type: string
const: committed
direction:
type: string
enum:
- forward
- backward
stepIndex:
type: number
value:
type: string
count:
type: number
required:
- kind
- direction
- stepIndex
- value
- count
additionalProperties: false
required:
- dimensions
additionalProperties: false
rawRows:
type: array
items:
type: object
propertyNames:
type: string
additionalProperties: {}
truncated:
type: boolean
required:
- rows
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: metric
dataset:
type: object
properties:
type:
type: string
const: metric
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: metric
metricId:
type: string
unit:
anyOf:
- type: string
- type: 'null'
denominatorUnit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- metricId
- unit
- denominatorUnit
additionalProperties: false
required:
- type
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
required:
- id
- dateCreated
- dateUpdated
- datasource
- status
- dateStart
- dateEnd
- result
- config
additionalProperties: false
- type: 'null'
query:
anyOf:
- title: Query
$ref: '#/components/schemas/Query'
- type: 'null'
explorationUrl:
description: >-
A direct link to view this exploration in the GrowthBook
Application.
type: string
message:
description: >-
Present when `exploration` is null, explaining why no
result was returned.
type: string
required:
- exploration
- query
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/product-analytics/metric-exploration'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/product-analytics/fact-table-exploration:
post:
operationId: postFactTableExploration
summary: Run a Fact Table based visualization
tags:
- AnalyticsExplorations
parameters:
- $ref: '#/components/parameters/cache'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: fact_table
dataset:
type: object
properties:
type:
type: string
const: fact_table
factTableId:
anyOf:
- type: string
- type: 'null'
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: fact_table
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
required:
- type
- factTableId
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
exploration:
anyOf:
- type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
datasource:
type: string
status:
type: string
enum:
- running
- success
- error
dateStart:
type: string
dateEnd:
type: string
error:
anyOf:
- type: string
- type: 'null'
result:
type: object
properties:
rows:
type: array
items:
type: object
properties:
dimensions:
type: array
items:
anyOf:
- type: string
- type: 'null'
values:
type: array
items:
type: object
properties:
metricId:
type: string
numerator:
anyOf:
- type: number
- type: 'null'
denominator:
anyOf:
- type: number
- type: 'null'
required:
- metricId
- numerator
- denominator
additionalProperties: false
steps:
type: array
items:
type: object
properties:
count:
type: number
timeFromPrevSumHrs:
anyOf:
- type: number
- type: 'null'
timeFromPrevSumSquaresHrs:
anyOf:
- type: number
- type: 'null'
required:
- count
- timeFromPrevSumHrs
- timeFromPrevSumSquaresHrs
additionalProperties: false
journey:
anyOf:
- type: object
properties:
kind:
type: string
const: path
direction:
type: string
enum:
- forward
- backward
levels:
type: array
items:
type: string
count:
type: number
required:
- kind
- direction
- levels
- count
additionalProperties: false
- type: object
properties:
kind:
type: string
const: committed
direction:
type: string
enum:
- forward
- backward
stepIndex:
type: number
value:
type: string
count:
type: number
required:
- kind
- direction
- stepIndex
- value
- count
additionalProperties: false
required:
- dimensions
additionalProperties: false
rawRows:
type: array
items:
type: object
propertyNames:
type: string
additionalProperties: {}
truncated:
type: boolean
required:
- rows
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: fact_table
dataset:
type: object
properties:
type:
type: string
const: fact_table
factTableId:
anyOf:
- type: string
- type: 'null'
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: fact_table
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
required:
- type
- factTableId
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
required:
- id
- dateCreated
- dateUpdated
- datasource
- status
- dateStart
- dateEnd
- result
- config
additionalProperties: false
- type: 'null'
query:
anyOf:
- title: Query
$ref: '#/components/schemas/Query'
- type: 'null'
explorationUrl:
description: >-
A direct link to view this exploration in the GrowthBook
Application.
type: string
message:
description: >-
Present when `exploration` is null, explaining why no
result was returned.
type: string
required:
- exploration
- query
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/product-analytics/fact-table-exploration'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/product-analytics/data-source-exploration:
post:
operationId: postDataSourceExploration
summary: Create a Data Source based visualization
tags:
- AnalyticsExplorations
parameters:
- $ref: '#/components/parameters/cache'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: data_source
dataset:
type: object
properties:
type:
type: string
const: data_source
table:
type: string
path:
type: string
timestampColumn:
type: string
columnTypes:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- string
- number
- date
- boolean
- other
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: data_source
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
required:
- type
- table
- path
- timestampColumn
- columnTypes
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
exploration:
anyOf:
- type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
datasource:
type: string
status:
type: string
enum:
- running
- success
- error
dateStart:
type: string
dateEnd:
type: string
error:
anyOf:
- type: string
- type: 'null'
result:
type: object
properties:
rows:
type: array
items:
type: object
properties:
dimensions:
type: array
items:
anyOf:
- type: string
- type: 'null'
values:
type: array
items:
type: object
properties:
metricId:
type: string
numerator:
anyOf:
- type: number
- type: 'null'
denominator:
anyOf:
- type: number
- type: 'null'
required:
- metricId
- numerator
- denominator
additionalProperties: false
steps:
type: array
items:
type: object
properties:
count:
type: number
timeFromPrevSumHrs:
anyOf:
- type: number
- type: 'null'
timeFromPrevSumSquaresHrs:
anyOf:
- type: number
- type: 'null'
required:
- count
- timeFromPrevSumHrs
- timeFromPrevSumSquaresHrs
additionalProperties: false
journey:
anyOf:
- type: object
properties:
kind:
type: string
const: path
direction:
type: string
enum:
- forward
- backward
levels:
type: array
items:
type: string
count:
type: number
required:
- kind
- direction
- levels
- count
additionalProperties: false
- type: object
properties:
kind:
type: string
const: committed
direction:
type: string
enum:
- forward
- backward
stepIndex:
type: number
value:
type: string
count:
type: number
required:
- kind
- direction
- stepIndex
- value
- count
additionalProperties: false
required:
- dimensions
additionalProperties: false
rawRows:
type: array
items:
type: object
propertyNames:
type: string
additionalProperties: {}
truncated:
type: boolean
required:
- rows
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: data_source
dataset:
type: object
properties:
type:
type: string
const: data_source
table:
type: string
path:
type: string
timestampColumn:
type: string
columnTypes:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- string
- number
- date
- boolean
- other
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: data_source
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
required:
- type
- table
- path
- timestampColumn
- columnTypes
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
required:
- id
- dateCreated
- dateUpdated
- datasource
- status
- dateStart
- dateEnd
- result
- config
additionalProperties: false
- type: 'null'
query:
anyOf:
- title: Query
$ref: '#/components/schemas/Query'
- type: 'null'
explorationUrl:
description: >-
A direct link to view this exploration in the GrowthBook
Application.
type: string
message:
description: >-
Present when `exploration` is null, explaining why no
result was returned.
type: string
required:
- exploration
- query
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/product-analytics/data-source-exploration'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/product-analytics/sql-exploration:
post:
operationId: postSqlExploration
summary: Create a SQL based visualization
tags:
- AnalyticsExplorations
parameters:
- $ref: '#/components/parameters/cache'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: sql
dataset:
type: object
properties:
type:
type: string
const: sql
sql:
type: string
timestampColumn:
anyOf:
- type: string
- type: 'null'
columnTypes:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- string
- number
- date
- boolean
- other
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: sql
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
hiddenColumns:
type: array
items:
type: string
required:
- type
- sql
- timestampColumn
- columnTypes
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
exploration:
anyOf:
- type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
datasource:
type: string
status:
type: string
enum:
- running
- success
- error
dateStart:
type: string
dateEnd:
type: string
error:
anyOf:
- type: string
- type: 'null'
result:
type: object
properties:
rows:
type: array
items:
type: object
properties:
dimensions:
type: array
items:
anyOf:
- type: string
- type: 'null'
values:
type: array
items:
type: object
properties:
metricId:
type: string
numerator:
anyOf:
- type: number
- type: 'null'
denominator:
anyOf:
- type: number
- type: 'null'
required:
- metricId
- numerator
- denominator
additionalProperties: false
steps:
type: array
items:
type: object
properties:
count:
type: number
timeFromPrevSumHrs:
anyOf:
- type: number
- type: 'null'
timeFromPrevSumSquaresHrs:
anyOf:
- type: number
- type: 'null'
required:
- count
- timeFromPrevSumHrs
- timeFromPrevSumSquaresHrs
additionalProperties: false
journey:
anyOf:
- type: object
properties:
kind:
type: string
const: path
direction:
type: string
enum:
- forward
- backward
levels:
type: array
items:
type: string
count:
type: number
required:
- kind
- direction
- levels
- count
additionalProperties: false
- type: object
properties:
kind:
type: string
const: committed
direction:
type: string
enum:
- forward
- backward
stepIndex:
type: number
value:
type: string
count:
type: number
required:
- kind
- direction
- stepIndex
- value
- count
additionalProperties: false
required:
- dimensions
additionalProperties: false
rawRows:
type: array
items:
type: object
propertyNames:
type: string
additionalProperties: {}
truncated:
type: boolean
required:
- rows
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: sql
dataset:
type: object
properties:
type:
type: string
const: sql
sql:
type: string
timestampColumn:
anyOf:
- type: string
- type: 'null'
columnTypes:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- string
- number
- date
- boolean
- other
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: sql
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
hiddenColumns:
type: array
items:
type: string
required:
- type
- sql
- timestampColumn
- columnTypes
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
required:
- id
- dateCreated
- dateUpdated
- datasource
- status
- dateStart
- dateEnd
- result
- config
additionalProperties: false
- type: 'null'
query:
anyOf:
- title: Query
$ref: '#/components/schemas/Query'
- type: 'null'
explorationUrl:
description: >-
A direct link to view this exploration in the GrowthBook
Application.
type: string
message:
description: >-
Present when `exploration` is null, explaining why no
result was returned.
type: string
required:
- exploration
- query
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/product-analytics/sql-exploration'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/product-analytics/funnel-exploration:
post:
operationId: postFunnelExploration
summary: Run a Funnel based visualization
tags:
- AnalyticsExplorations
parameters:
- $ref: '#/components/parameters/cache'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: funnel
dataset:
type: object
properties:
type:
type: string
const: funnel
unit:
anyOf:
- type: string
- type: 'null'
steps:
maxItems: 20
type: array
items:
type: object
properties:
name:
type: string
factTableId:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
optional:
type: boolean
conversionWindow:
anyOf:
- type: object
properties:
unit:
type: string
enum:
- weeks
- days
- hours
- minutes
value:
type: number
exclusiveMinimum: 0
required:
- unit
- value
additionalProperties: false
- type: 'null'
required:
- name
- factTableId
- rowFilters
- optional
additionalProperties: false
concurrencyWindowSeconds:
type: integer
minimum: 0
yAxisScale:
type: string
enum:
- count
- percent
required:
- type
- unit
- steps
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
exploration:
anyOf:
- type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
datasource:
type: string
status:
type: string
enum:
- running
- success
- error
dateStart:
type: string
dateEnd:
type: string
error:
anyOf:
- type: string
- type: 'null'
result:
type: object
properties:
rows:
type: array
items:
type: object
properties:
dimensions:
type: array
items:
anyOf:
- type: string
- type: 'null'
values:
type: array
items:
type: object
properties:
metricId:
type: string
numerator:
anyOf:
- type: number
- type: 'null'
denominator:
anyOf:
- type: number
- type: 'null'
required:
- metricId
- numerator
- denominator
additionalProperties: false
steps:
type: array
items:
type: object
properties:
count:
type: number
timeFromPrevSumHrs:
anyOf:
- type: number
- type: 'null'
timeFromPrevSumSquaresHrs:
anyOf:
- type: number
- type: 'null'
required:
- count
- timeFromPrevSumHrs
- timeFromPrevSumSquaresHrs
additionalProperties: false
journey:
anyOf:
- type: object
properties:
kind:
type: string
const: path
direction:
type: string
enum:
- forward
- backward
levels:
type: array
items:
type: string
count:
type: number
required:
- kind
- direction
- levels
- count
additionalProperties: false
- type: object
properties:
kind:
type: string
const: committed
direction:
type: string
enum:
- forward
- backward
stepIndex:
type: number
value:
type: string
count:
type: number
required:
- kind
- direction
- stepIndex
- value
- count
additionalProperties: false
required:
- dimensions
additionalProperties: false
rawRows:
type: array
items:
type: object
propertyNames:
type: string
additionalProperties: {}
truncated:
type: boolean
required:
- rows
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: funnel
dataset:
type: object
properties:
type:
type: string
const: funnel
unit:
anyOf:
- type: string
- type: 'null'
steps:
maxItems: 20
type: array
items:
type: object
properties:
name:
type: string
factTableId:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
optional:
type: boolean
conversionWindow:
anyOf:
- type: object
properties:
unit:
type: string
enum:
- weeks
- days
- hours
- minutes
value:
type: number
exclusiveMinimum: 0
required:
- unit
- value
additionalProperties: false
- type: 'null'
required:
- name
- factTableId
- rowFilters
- optional
additionalProperties: false
concurrencyWindowSeconds:
type: integer
minimum: 0
yAxisScale:
type: string
enum:
- count
- percent
required:
- type
- unit
- steps
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
required:
- id
- dateCreated
- dateUpdated
- datasource
- status
- dateStart
- dateEnd
- result
- config
additionalProperties: false
- type: 'null'
query:
anyOf:
- title: Query
$ref: '#/components/schemas/Query'
- type: 'null'
explorationUrl:
description: >-
A direct link to view this exploration in the GrowthBook
Application.
type: string
message:
description: >-
Present when `exploration` is null, explaining why no
result was returned.
type: string
required:
- exploration
- query
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/product-analytics/funnel-exploration'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/product-analytics/journey-exploration:
post:
operationId: postJourneyExploration
summary: Run a User Journey based visualization
tags:
- AnalyticsExplorations
parameters:
- $ref: '#/components/parameters/cache'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: journey
dataset:
type: object
properties:
type:
type: string
const: journey
factTableId:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
stepColumns:
maxItems: 3
type: array
items:
type: string
stepGroups:
maxItems: 25
type: array
items:
type: object
properties:
column:
type: string
pattern:
type: string
required:
- column
- pattern
additionalProperties: false
anchorStepValues:
anyOf:
- type: array
items:
type: string
- type: 'null'
direction:
type: string
enum:
- forward
- backward
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
path:
maxItems: 15
type: array
items:
type: object
properties:
value:
type: string
required:
- value
additionalProperties: false
lookaheadDepth:
type: integer
minimum: 1
maximum: 4
optionsPerStep:
type: array
items:
type: integer
minimum: 2
maximum: 50
heightScale:
type: string
enum:
- relative
- absolute
required:
- type
- factTableId
- unit
- stepColumns
- anchorStepValues
- direction
- rowFilters
- path
- lookaheadDepth
- optionsPerStep
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
exploration:
anyOf:
- type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
datasource:
type: string
status:
type: string
enum:
- running
- success
- error
dateStart:
type: string
dateEnd:
type: string
error:
anyOf:
- type: string
- type: 'null'
result:
type: object
properties:
rows:
type: array
items:
type: object
properties:
dimensions:
type: array
items:
anyOf:
- type: string
- type: 'null'
values:
type: array
items:
type: object
properties:
metricId:
type: string
numerator:
anyOf:
- type: number
- type: 'null'
denominator:
anyOf:
- type: number
- type: 'null'
required:
- metricId
- numerator
- denominator
additionalProperties: false
steps:
type: array
items:
type: object
properties:
count:
type: number
timeFromPrevSumHrs:
anyOf:
- type: number
- type: 'null'
timeFromPrevSumSquaresHrs:
anyOf:
- type: number
- type: 'null'
required:
- count
- timeFromPrevSumHrs
- timeFromPrevSumSquaresHrs
additionalProperties: false
journey:
anyOf:
- type: object
properties:
kind:
type: string
const: path
direction:
type: string
enum:
- forward
- backward
levels:
type: array
items:
type: string
count:
type: number
required:
- kind
- direction
- levels
- count
additionalProperties: false
- type: object
properties:
kind:
type: string
const: committed
direction:
type: string
enum:
- forward
- backward
stepIndex:
type: number
value:
type: string
count:
type: number
required:
- kind
- direction
- stepIndex
- value
- count
additionalProperties: false
required:
- dimensions
additionalProperties: false
rawRows:
type: array
items:
type: object
propertyNames:
type: string
additionalProperties: {}
truncated:
type: boolean
required:
- rows
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: journey
dataset:
type: object
properties:
type:
type: string
const: journey
factTableId:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
stepColumns:
maxItems: 3
type: array
items:
type: string
stepGroups:
maxItems: 25
type: array
items:
type: object
properties:
column:
type: string
pattern:
type: string
required:
- column
- pattern
additionalProperties: false
anchorStepValues:
anyOf:
- type: array
items:
type: string
- type: 'null'
direction:
type: string
enum:
- forward
- backward
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
path:
maxItems: 15
type: array
items:
type: object
properties:
value:
type: string
required:
- value
additionalProperties: false
lookaheadDepth:
type: integer
minimum: 1
maximum: 4
optionsPerStep:
type: array
items:
type: integer
minimum: 2
maximum: 50
heightScale:
type: string
enum:
- relative
- absolute
required:
- type
- factTableId
- unit
- stepColumns
- anchorStepValues
- direction
- rowFilters
- path
- lookaheadDepth
- optionsPerStep
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
required:
- id
- dateCreated
- dateUpdated
- datasource
- status
- dateStart
- dateEnd
- result
- config
additionalProperties: false
- type: 'null'
query:
anyOf:
- title: Query
$ref: '#/components/schemas/Query'
- type: 'null'
explorationUrl:
description: >-
A direct link to view this exploration in the GrowthBook
Application.
type: string
message:
description: >-
Present when `exploration` is null, explaining why no
result was returned.
type: string
required:
- exploration
- query
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/product-analytics/journey-exploration'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/product-analytics/search:
get:
operationId: searchProductAnalyticsResources
summary: Search Product Analytics resources
tags:
- AnalyticsExplorations
parameters:
- $ref: '#/components/parameters/query'
- name: limit
in: query
description: ''
schema:
default: 10
type: integer
minimum: 1
maximum: 20
- $ref: '#/components/parameters/skip'
- name: datasourceId
in: query
description: ''
schema:
type: string
minLength: 1
maxLength: 255
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
matches:
type: array
items:
anyOf:
- type: object
properties:
kind:
type: string
const: metric
explorerType:
type: string
const: metric
id:
type: string
name:
type: string
type:
type: string
official:
type: boolean
description:
anyOf:
- type: string
- type: 'null'
owner:
anyOf:
- type: string
- type: 'null'
ownerEmail:
type: string
tags:
type: array
items:
type: string
required:
- kind
- explorerType
- id
- name
- type
- official
- description
- owner
- tags
additionalProperties: false
- type: object
properties:
kind:
type: string
const: fact_table
explorerType:
type: string
const: fact_table
id:
type: string
name:
type: string
official:
type: boolean
eventName:
anyOf:
- type: string
- type: 'null'
columnCount:
type: integer
required:
- kind
- explorerType
- id
- name
- official
- eventName
- columnCount
additionalProperties: false
totalMetrics:
type: integer
totalFactTables:
type: integer
totalMatches:
type: integer
skip:
type: integer
limit:
type: integer
required:
- matches
- totalMetrics
- totalFactTables
- totalMatches
- skip
- limit
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/product-analytics/search' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/product-analytics/columns:
get:
operationId: getProductAnalyticsColumns
summary: List columns available to a Product Analytics exploration
tags:
- AnalyticsExplorations
parameters:
- name: source
in: query
required: true
description: ''
schema:
type: string
enum:
- fact_table
- metric
- name: factTableId
in: query
description: ''
schema:
type: string
minLength: 1
maxLength: 255
- $ref: '#/components/parameters/metricIds'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
columns:
type: array
items:
$ref: '#/components/schemas/columns'
userIdTypes:
type: array
items:
type: string
metrics:
type: array
items:
$ref: '#/components/schemas/metrics'
unitNote:
type: string
required:
- columns
- userIdTypes
- unitNote
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/product-analytics/columns' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/product-analytics/column-values:
post:
operationId: getProductAnalyticsColumnValues
summary: Fetch values for Product Analytics string columns
tags:
- AnalyticsExplorations
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
source:
type: string
enum:
- fact_table
- metric
factTableId:
type: string
minLength: 1
maxLength: 255
metricIds:
minItems: 1
maxItems: 20
type: array
items:
type: string
minLength: 1
maxLength: 255
columns:
minItems: 1
maxItems: 5
type: array
items:
type: string
minLength: 1
maxLength: 255
searchTerm:
type: string
maxLength: 200
limit:
default: 20
type: integer
minimum: 1
maximum: 50
required:
- source
- columns
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
values:
$ref: '#/components/schemas/values'
warnings:
type: array
items:
type: string
required:
- values
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/product-analytics/column-values' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/product-analytics/explorations/{id}:
get:
operationId: getProductAnalyticsExploration
summary: Get a Product Analytics exploration
tags:
- AnalyticsExplorations
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
minLength: 1
maxLength: 255
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
exploration:
$ref: '#/components/schemas/AnalyticsExploration'
query:
anyOf:
- title: Query
$ref: '#/components/schemas/Query'
- type: 'null'
explorationUrl:
type: string
required:
- exploration
- query
- explorationUrl
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/product-analytics/explorations/{id}'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedule-templates/{id}:
get:
operationId: getRampScheduleTemplate
summary: Get a single rampScheduleTemplate
tags:
- RampScheduleTemplates
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
rampScheduleTemplate:
$ref: '#/components/schemas/RampScheduleTemplate'
required:
- rampScheduleTemplate
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/ramp-schedule-templates/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteRampScheduleTemplate
summary: Delete a single rampScheduleTemplate
tags:
- RampScheduleTemplates
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/ramp-schedule-templates/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: updateRampScheduleTemplate
summary: Update a single rampScheduleTemplate
tags:
- RampScheduleTemplates
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
steps:
type: array
items:
type: object
properties:
interval:
description: >-
Hold duration in seconds before this step's gates are
evaluated. null = no time gate (advance as soon as
holdConditions clear).
anyOf:
- type: number
exclusiveMinimum: 0
- type: 'null'
approvalNotes:
anyOf:
- type: string
- type: 'null'
monitored:
description: >-
When true, this step runs A/B traffic analysis while
active. Treatment = [0, coverage), control = [0.5,
0.5+coverage). Arms are equal-sized and non-adjacent:
step-ups only add users, never reassign existing ones.
The UI caps monitored-step coverage at 0.5 so control
end never exceeds 1.0. The SDK uses explicit hash
ranges on the experiment rule to prevent bucketing
shifts across monitored/unmonitored transitions.
type: boolean
holdConditions:
type: object
properties:
minSampleSize:
type: integer
exclusiveMinimum: 0
requiresApproval:
type: boolean
additionalProperties: false
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'
enabled:
anyOf:
- type: boolean
- type: 'null'
force:
description: >-
Ignored: templates never carry force values.
Accepted so a schedule's steps can be copied
into a template.
required:
- ruleId
additionalProperties: false
required:
- targetType
- targetId
- patch
additionalProperties: false
required:
- interval
- actions
additionalProperties: false
endPatch:
type: object
properties:
coverage:
type: number
minimum: 0
maximum: 1
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
allEnvironments:
type: boolean
environments:
type: array
items:
type: string
additionalProperties: false
official:
type: boolean
monitoringConfig:
anyOf:
- 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. Mutually exclusive with
the deprecated `exposureQueryId`.
type: object
properties:
id:
description: >-
The ID of one of the data source's assignment
queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the
query must declare. Required when selecting a
different assignment query that declares
several. Otherwise defaults to the current
identifier type, or the query's only one. Null
is treated as omitted, so a response's value can
be sent back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
exposureQueryId:
deprecated: true
description: >-
Deprecated: use `exposureQuery`. Rejected when
selecting a different assignment query that declares
several identifier types; set
`exposureQuery.identifierType` instead.
type: string
required:
- datasourceId
- guardrailMetricIds
additionalProperties: false
- type: 'null'
lockdownConfig:
type: object
properties:
mode:
type: string
enum:
- none
- locked
required:
- mode
additionalProperties: false
order:
description: Display order within the org (lower sorts first).
type: number
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
rampScheduleTemplate:
$ref: '#/components/schemas/RampScheduleTemplate'
required:
- rampScheduleTemplate
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/ramp-schedule-templates/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedule-templates:
post:
operationId: createRampScheduleTemplate
summary: Create a single rampScheduleTemplate
tags:
- RampScheduleTemplates
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
steps:
type: array
items:
type: object
properties:
interval:
description: >-
Hold duration in seconds before this step's gates are
evaluated. null = no time gate (advance as soon as
holdConditions clear).
anyOf:
- type: number
exclusiveMinimum: 0
- type: 'null'
approvalNotes:
anyOf:
- type: string
- type: 'null'
monitored:
description: >-
When true, this step runs A/B traffic analysis while
active. Treatment = [0, coverage), control = [0.5,
0.5+coverage). Arms are equal-sized and non-adjacent:
step-ups only add users, never reassign existing ones.
The UI caps monitored-step coverage at 0.5 so control
end never exceeds 1.0. The SDK uses explicit hash
ranges on the experiment rule to prevent bucketing
shifts across monitored/unmonitored transitions.
type: boolean
holdConditions:
type: object
properties:
minSampleSize:
type: integer
exclusiveMinimum: 0
requiresApproval:
type: boolean
additionalProperties: false
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'
enabled:
anyOf:
- type: boolean
- type: 'null'
force:
description: >-
Ignored: templates never carry force values.
Accepted so a schedule's steps can be copied
into a template.
required:
- ruleId
additionalProperties: false
required:
- targetType
- targetId
- patch
additionalProperties: false
required:
- interval
- actions
additionalProperties: false
endPatch:
type: object
properties:
coverage:
type: number
minimum: 0
maximum: 1
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
allEnvironments:
type: boolean
environments:
type: array
items:
type: string
additionalProperties: false
official:
type: boolean
monitoringConfig:
anyOf:
- 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. Mutually exclusive with
the deprecated `exposureQueryId`.
type: object
properties:
id:
description: >-
The ID of one of the data source's assignment
queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the
query must declare. Required when selecting a
different assignment query that declares
several. Otherwise defaults to the current
identifier type, or the query's only one. Null
is treated as omitted, so a response's value can
be sent back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
exposureQueryId:
deprecated: true
description: >-
Deprecated: use `exposureQuery`. Rejected when
selecting a different assignment query that declares
several identifier types; set
`exposureQuery.identifierType` instead.
type: string
required:
- datasourceId
- guardrailMetricIds
additionalProperties: false
- type: 'null'
lockdownConfig:
type: object
properties:
mode:
type: string
enum:
- none
- locked
required:
- mode
additionalProperties: false
order:
description: >-
Display order within the org (lower sorts first). Omit to
append to the end.
type: number
required:
- name
- steps
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
rampScheduleTemplate:
$ref: '#/components/schemas/RampScheduleTemplate'
required:
- rampScheduleTemplate
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/ramp-schedule-templates' \
-H 'Authorization: Bearer YOUR_API_KEY'
get:
operationId: listRampScheduleTemplates
summary: Get all rampScheduleTemplates
tags:
- RampScheduleTemplates
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
rampScheduleTemplates:
type: array
items:
$ref: '#/components/schemas/RampScheduleTemplate'
required:
- rampScheduleTemplates
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X GET
'https://api.growthbook.io/api/v1/ramp-schedule-templates' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/ramp-schedules/{id}:
get:
operationId: getRampSchedule
summary: Get a single rampSchedule
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/ramp-schedules/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteRampSchedule
summary: Delete a single rampSchedule
description: >
Permanently deletes a ramp schedule. This does not undo any rule patches
that
were already applied by completed steps.
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X DELETE
'https://api.growthbook.io/api/v1/ramp-schedules/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: updateRampSchedule
summary: Update a single rampSchedule
description: >
Updates the name, steps, endActions, startDate, or cutoffDate of a ramp
schedule.
Only allowed when the schedule is in `pending`, `ready`, or `paused`
status.
Changing `steps`, `startActions`, `endActions`, `startDate`, or
`cutoffDate` on a
schedule that is attached to a rule skips the revision review flow, so
when the
organization requires review anywhere it is limited to credentials that
may
bypass approval. Otherwise stage a new plan on a draft revision and
publish it.
**targetId shorthand**: When providing `steps` or `endActions`, you may
omit `targetId`
(or pass `"t1"`) in each action. If the schedule has exactly one active
target, the server
will resolve it automatically. For schedules with multiple targets,
provide the explicit
target UUID from `targets[].id`.
**Coverage on monitored steps**: See the create endpoint description for
details
on how `coverage` is interpreted for monitored steps (total enrollment,
not
variation-1 exposure).
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
steps:
type: array
items:
type: object
properties:
interval:
description: >-
Hold duration in seconds before this step's gates are
evaluated. null = no time gate (advance as soon as
holdConditions clear).
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'
required:
- ruleId
additionalProperties: false
additionalProperties: false
approvalNotes:
anyOf:
- type: string
- type: 'null'
monitored:
description: >-
When true, this step runs A/B traffic analysis while
active. Enrolled users are split 50/50 between control
and variation, so a coverage of 1.0 means 50% of users
see the variation. The SDK uses hash-based filters on
the experiment rule to prevent bucketing shifts when
transitioning between monitored and unmonitored steps.
default: false
type: boolean
holdConditions:
type: object
properties:
minSampleSize:
type: integer
exclusiveMinimum: 0
requiresApproval:
type: boolean
additionalProperties: false
required:
- interval
additionalProperties: false
startActions:
type: array
items:
type: object
properties:
targetType:
type: string
const: feature-rule
targetId:
type: string
patch:
description: >-
The rule's pre-ramp state, and the only place a plan
sets hashAttribute, seed or hashVersion.
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'
required:
- ruleId
additionalProperties: false
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'
required:
- ruleId
additionalProperties: false
additionalProperties: false
startDate:
anyOf:
- type: string
format: date-time
- type: 'null'
cutoffDate:
anyOf:
- type: string
format: date-time
- type: 'null'
monitoringConfig:
anyOf:
- 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. Mutually exclusive with
the deprecated `exposureQueryId`.
type: object
properties:
id:
description: >-
The ID of one of the data source's assignment
queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the
query must declare. Required when selecting a
different assignment query that declares
several. Otherwise defaults to the current
identifier type, or the query's only one. Null
is treated as omitted, so a response's value can
be sent back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
exposureQueryId:
deprecated: true
description: >-
Deprecated: use `exposureQuery`. Rejected when
selecting a different assignment query that declares
several identifier types; set
`exposureQuery.identifierType` instead.
type: string
required:
- datasourceId
- guardrailMetricIds
additionalProperties: false
- type: 'null'
experimentHealthAction:
type: string
enum:
- rollback
- hold
- warn
lockdownConfig:
description: >-
When mode is 'locked', blocks all feature edits while the
ramp is actively running.
type: object
properties:
mode:
type: string
enum:
- none
- locked
required:
- mode
additionalProperties: false
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X PUT 'https://api.growthbook.io/api/v1/ramp-schedules/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/learnings/{id}:
get:
operationId: getLearning
summary: Get a single learning
tags:
- Learnings
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
learning:
$ref: '#/components/schemas/Learning'
required:
- learning
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/learnings/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deleteLearning
summary: Delete a single learning
tags:
- Learnings
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X DELETE 'https://api.growthbook.io/api/v1/learnings/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: updateLearning
summary: Update a single learning
tags:
- Learnings
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
type: string
text:
type: string
tags:
type: array
items:
type: string
supportingExperimentIds:
type: array
items:
type: string
contradictingExperimentIds:
type: array
items:
type: string
projects:
type: array
items:
type: string
status:
description: >-
ID of a learning status configured at the org level
(Settings → General → Experiment Settings). Omit or pass an
empty string for no status.
type: string
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
learning:
$ref: '#/components/schemas/Learning'
required:
- learning
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X PUT 'https://api.growthbook.io/api/v1/learnings/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/learnings:
post:
operationId: createLearning
summary: Create a single learning
tags:
- Learnings
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
type: string
text:
type: string
tags:
type: array
items:
type: string
supportingExperimentIds:
type: array
items:
type: string
contradictingExperimentIds:
type: array
items:
type: string
projects:
type: array
items:
type: string
status:
description: >-
ID of a learning status configured at the org level
(Settings → General → Experiment Settings). Omit or pass an
empty string for no status.
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
required:
- title
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
learning:
$ref: '#/components/schemas/Learning'
required:
- learning
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/learnings' \
-H 'Authorization: Bearer YOUR_API_KEY'
get:
operationId: listLearnings
summary: Get all learnings
tags:
- Learnings
parameters:
- name: projectId
in: query
description: ''
schema:
type: string
- name: experimentId
in: query
description: Only return learnings that reference this experiment
schema:
description: Only return learnings that reference this experiment
type: string
- name: tag
in: query
description: ''
schema:
type: string
- name: status
in: query
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
learnings:
type: array
items:
$ref: '#/components/schemas/Learning'
required:
- learnings
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/learnings' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/learnings/search:
post:
operationId: searchLearnings
summary: Search saved Learnings by meaning rather than keyword
tags:
- Learnings
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
query:
description: Natural-language query to rank learnings against
type: string
limit:
type: integer
exclusiveMinimum: 0
maximum: 50
projectId:
type: string
required:
- query
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
learnings:
type: array
items:
$ref: '#/components/schemas/learnings'
required:
- learnings
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/learnings/search' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/holdouts/{id}:
get:
operationId: getHoldout
summary: Get a single holdout
tags:
- Holdouts
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
holdout:
$ref: '#/components/schemas/Holdout'
required:
- holdout
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/holdouts/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: updateHoldout
summary: Update a single holdout
description: >-
Updates a Holdout. Use the start, start-analysis, and stop endpoints to
move it through its lifecycle.
tags:
- Holdouts
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name. Put details in `description`.
type: string
minLength: 1
description:
description: Markdown. Put context here, not in the name.
type: string
maxLength: 10000
projects:
description: >-
Project IDs this Holdout applies to. Send an empty array for
All Projects.
type: array
items:
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
tags:
description: >-
Tags for filtering and grouping. Use these instead of
encoding groups in names.
type: array
items:
type: string
archived:
type: boolean
skipAsDefaultHoldout:
description: >-
When true, this Holdout is not selected automatically when
creating Feature Flags or Experiments in Projects assigned
to the Holdout.
type: boolean
holdoutSize:
description: >-
Proportion of traffic placed in the holdout group (e.g. 0.05
for 5%). An equally sized comparison group is sampled from
the remaining traffic for measurement, so 2× this value
enters the holdout experiment in total. Must be greater than
0 and at most 0.5.
type: number
exclusiveMinimum: 0
maximum: 0.5
hashAttribute:
type: string
targetingCondition:
type: string
savedGroupTargeting:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
datasourceId:
type: string
assignmentQuery:
description: >-
The assignment query, grouping its ID with the identifier
type analyzed on. Mutually exclusive with the deprecated
`assignmentQueryId`.
type: object
properties:
id:
description: The ID of one of the data source's assignment queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the query must
declare. Required when selecting a different assignment
query that declares several. Otherwise defaults to the
current identifier type, or the query's only one. Null
is treated as omitted, so a response's value can be sent
back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
assignmentQueryId:
deprecated: true
description: >-
Deprecated: use `assignmentQuery`. Rejected when selecting a
different assignment query that declares several identifier
types; set `assignmentQuery.identifierType` instead.
type: string
goalMetrics:
type: array
items:
type: string
secondaryMetrics:
type: array
items:
type: string
statsEngine:
description: Statistics engine used to analyze this Holdout.
type: string
enum:
- bayesian
- frequentist
environments:
description: >-
Replaces the entire per-environment state. Environments not
listed are disabled.
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
enabled:
description: Whether the Holdout is active in this environment.
type: boolean
required:
- enabled
additionalProperties: false
statusUpdateSchedule:
anyOf:
- description: >-
Automatic stage transitions for the Holdout. Dates must
be consecutive: `startAt` before `startAnalysisPeriodAt`
before `stopAt`. Send `null` to delete the schedule.
type: object
properties:
startAt:
description: >-
ISO datetime to move the Holdout from `draft` to
`running`. Must be in the future while the Holdout
is still a draft.
type: string
format: date-time
startAnalysisPeriodAt:
description: >-
ISO datetime to move the Holdout from `running` to
`analysis-period`. Requires `startAt` while the
Holdout is still a draft.
type: string
format: date-time
stopAt:
description: >-
ISO datetime to stop the Holdout. Requires
`startAnalysisPeriodAt` unless the analysis period
has already begun.
type: string
format: date-time
additionalProperties: false
- type: 'null'
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
holdout:
$ref: '#/components/schemas/Holdout'
required:
- holdout
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X PUT 'https://api.growthbook.io/api/v1/holdouts/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/holdouts:
post:
operationId: createHoldout
summary: Create a single holdout
description: >-
Creates a Holdout. The Holdout starts in the `draft` stage. Use the
start endpoint to start it.
tags:
- Holdouts
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: Short display name. Put details in `description`.
type: string
minLength: 1
description:
description: Markdown. Put context here, not in the name.
type: string
maxLength: 10000
projects:
description: >-
Project IDs this Holdout applies to. Omit or send an empty
array for All Projects.
type: array
items:
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
tags:
description: >-
Tags for filtering and grouping. Use these instead of
encoding groups in names.
type: array
items:
type: string
skipAsDefaultHoldout:
description: >-
When true, this Holdout is not selected automatically when
creating Feature Flags or Experiments in Projects assigned
to the Holdout.
type: boolean
holdoutSize:
description: >-
Proportion of traffic held out, expressed as a decimal (e.g.
0.05 for 5%). An equally-sized control group is bucketed
alongside it. Defaults to 0.05. Maximum 0.5.
type: number
exclusiveMinimum: 0
maximum: 0.5
hashAttribute:
type: string
targetingCondition:
description: Targeting condition as a JSON string.
type: string
savedGroupTargeting:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
datasourceId:
type: string
assignmentQuery:
description: >-
The assignment query, grouping its ID with the identifier
type analyzed on. Mutually exclusive with the deprecated
`assignmentQueryId`.
type: object
properties:
id:
description: The ID of one of the data source's assignment queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the query must
declare. Required when selecting a different assignment
query that declares several. Otherwise defaults to the
current identifier type, or the query's only one. Null
is treated as omitted, so a response's value can be sent
back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
assignmentQueryId:
deprecated: true
description: >-
Deprecated: use `assignmentQuery`. Rejected when selecting a
different assignment query that declares several identifier
types; set `assignmentQuery.identifierType` instead.
type: string
goalMetrics:
type: array
items:
type: string
secondaryMetrics:
type: array
items:
type: string
statsEngine:
description: Statistics engine used to analyze this Holdout.
type: string
enum:
- bayesian
- frequentist
environments:
description: >-
Per-environment state, keyed by environment ID. Environments
not listed are disabled.
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
enabled:
description: Whether the Holdout is active in this environment.
type: boolean
required:
- enabled
additionalProperties: false
statusUpdateSchedule:
description: >-
Automatic stage transitions for the Holdout. Dates must be
consecutive: `startAt` before `startAnalysisPeriodAt` before
`stopAt`. Send `null` to delete the schedule.
type: object
properties:
startAt:
description: >-
ISO datetime to move the Holdout from `draft` to
`running`. Must be in the future while the Holdout is
still a draft.
type: string
format: date-time
startAnalysisPeriodAt:
description: >-
ISO datetime to move the Holdout from `running` to
`analysis-period`. Requires `startAt` while the Holdout
is still a draft.
type: string
format: date-time
stopAt:
description: >-
ISO datetime to stop the Holdout. Requires
`startAnalysisPeriodAt` unless the analysis period has
already begun.
type: string
format: date-time
additionalProperties: false
required:
- name
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
holdout:
$ref: '#/components/schemas/Holdout'
required:
- holdout
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/holdouts' \
-H 'Authorization: Bearer YOUR_API_KEY'
get:
operationId: listHoldouts
summary: Get all holdouts
tags:
- Holdouts
parameters:
- name: projectId
in: query
description: ''
schema:
type: string
- name: datasourceId
in: query
description: ''
schema:
type: string
- $ref: '#/components/parameters/stage'
- name: archived
in: query
description: >-
Filter by archived state. Omit to return both archived and
unarchived Holdouts.
schema:
description: >-
Filter by archived state. Omit to return both archived and
unarchived Holdouts.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
holdouts:
type: array
items:
$ref: '#/components/schemas/Holdout'
required:
- holdouts
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/holdouts' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/holdouts/{id}/start:
post:
operationId: startHoldout
summary: Start the Holdout's Active Period
description: >-
Feature Flags and Experiments can be added during this period while the
Holdout measures their cumulative impact.
tags:
- Holdouts
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
holdout:
$ref: '#/components/schemas/Holdout'
required:
- holdout
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
'409':
description: Conflict
content:
application/json:
schema:
type: object
description: Resource is not in a valid status for this operation
properties:
message:
type: string
code:
type: string
enum:
- invalid_status
details:
$ref: '#/components/schemas/ApiErrorInvalidStatusDetails'
required:
- message
- code
- details
x-codeSamples:
- lang: cURL
source: >-
curl -X POST 'https://api.growthbook.io/api/v1/holdouts/{id}/start'
\
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/holdouts/{id}/start-analysis:
post:
operationId: startHoldoutAnalysis
summary: Start the Holdout's Analysis Period
description: >-
Move the holdout into an analysis phase. New Feature Flags and
Experiments can no longer be added, but existing traffic splits remain
active for existing and new traffic. Results exclude data from before
the analysis period so you can measure the cumulative impact after
changes are frozen.
tags:
- Holdouts
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
holdout:
$ref: '#/components/schemas/Holdout'
required:
- holdout
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
'409':
description: Conflict
content:
application/json:
schema:
type: object
description: Resource is not in a valid status for this operation
properties:
message:
type: string
code:
type: string
enum:
- invalid_status
details:
$ref: '#/components/schemas/ApiErrorInvalidStatusDetails'
required:
- message
- code
- details
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/holdouts/{id}/start-analysis' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/holdouts/{id}/stop:
post:
operationId: stopHoldout
summary: Stop a Holdout
tags:
- Holdouts
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
holdout:
$ref: '#/components/schemas/Holdout'
required:
- holdout
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
'409':
description: Conflict
content:
application/json:
schema:
type: object
description: Resource is not in a valid status for this operation
properties:
message:
type: string
code:
type: string
enum:
- invalid_status
details:
$ref: '#/components/schemas/ApiErrorInvalidStatusDetails'
required:
- message
- code
- details
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/holdouts/{id}/stop' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/auto-runs:
post:
operationId: createAutoRun
summary: Create a single autoRun
tags:
- AutoRuns
requestBody:
required: true
content:
application/json:
schema:
description: Open an auto run. Everything it creates is appended afterwards
type: object
properties:
source:
type: string
enum:
- cli-wizard
- skill
- eppo-import
agent:
type: string
maxLength: 50
metadata:
type: object
propertyNames:
type: string
maxLength: 60
additionalProperties:
anyOf:
- type: string
maxLength: 500
- type: number
- type: boolean
- type: 'null'
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
autoRun:
$ref: '#/components/schemas/AutoRun'
required:
- autoRun
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/auto-runs' \
-H 'Authorization: Bearer YOUR_API_KEY'
get:
operationId: listAutoRuns
summary: Get all autoRuns
tags:
- AutoRuns
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
autoRuns:
type: array
items:
$ref: '#/components/schemas/AutoRun'
required:
- autoRuns
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/auto-runs' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/auto-runs/{id}:
get:
operationId: getAutoRun
summary: Get a single autoRun
tags:
- AutoRuns
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
autoRun:
$ref: '#/components/schemas/AutoRun'
required:
- autoRun
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/auto-runs/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: updateAutoRun
summary: Update a single autoRun
tags:
- AutoRuns
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
description: Record the outcome of an auto run
type: object
properties:
metadata:
type: object
propertyNames:
type: string
maxLength: 60
additionalProperties:
anyOf:
- type: string
maxLength: 500
- type: number
- type: boolean
- type: 'null'
checks:
maxItems: 50
type: array
items:
type: object
properties:
name:
type: string
maxLength: 100
ok:
type: boolean
required:
type: boolean
required:
- name
- ok
- required
additionalProperties: false
outcome:
type: string
enum:
- completed
- partial
- failed
failureReason:
type: string
maxLength: 1000
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
autoRun:
$ref: '#/components/schemas/AutoRun'
required:
- autoRun
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X PUT 'https://api.growthbook.io/api/v1/auto-runs/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/auto-runs/{id}/artifacts:
post:
operationId: appendAutoRunArtifact
summary: Record something an auto run created
tags:
- AutoRuns
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
description: Record something the run created
type: object
properties:
kind:
type: string
enum:
- sdk-connection
- feature
- experiment
- attribute
- metric
- fact-table
- saved-group
- environment
- tag
id:
description: Id, or key for Feature Flags
type: string
maxLength: 200
label:
type: string
maxLength: 200
by:
type: string
enum:
- developer
- growthbook
detail:
description: Evidence or summary, e.g. 'boolean, off in dev'
anyOf:
- type: string
maxLength: 500
- type: 'null'
externalId:
anyOf:
- type: string
maxLength: 200
- type: 'null'
action:
type: string
enum:
- created
- updated
- existing
- deleted
- failed
required:
- kind
- id
- label
- by
- detail
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
id: AutoRun
type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
source:
type: string
enum:
- cli-wizard
- skill
- eppo-import
agent:
anyOf:
- type: string
- type: 'null'
createdBy:
description: Id of the user who ran the wizard
anyOf:
- type: string
- type: 'null'
metadata:
$ref: '#/components/schemas/metadata'
artifacts:
type: array
items:
$ref: '#/components/schemas/artifacts'
checks:
type: array
items:
$ref: '#/components/schemas/checks'
outcome:
anyOf:
- type: string
enum:
- completed
- partial
- failed
- type: 'null'
failureReason:
anyOf:
- type: string
- type: 'null'
dateCompleted:
anyOf:
- type: string
format: date-time
- type: 'null'
url:
description: >-
Absolute URL of the run's page in the app. Built
server-side so callers never guess the app origin
type: string
required:
- id
- dateCreated
- dateUpdated
- source
- agent
- createdBy
- metadata
- artifacts
- checks
- outcome
- failureReason
- dateCompleted
- url
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: >-
curl -X POST
'https://api.growthbook.io/api/v1/auto-runs/{id}/artifacts' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/populations:
get:
operationId: listPopulations
summary: Get all populations
tags:
- Populations
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
limit:
type: integer
offset:
type: integer
count:
type: integer
total:
type: integer
hasMore:
type: boolean
nextOffset:
anyOf:
- type: integer
- type: 'null'
populations:
type: array
items:
$ref: '#/components/schemas/Population'
required:
- limit
- offset
- count
- total
- hasMore
- nextOffset
- populations
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/populations' \
-H 'Authorization: Bearer YOUR_API_KEY'
post:
operationId: createPopulation
summary: Create a single population
tags:
- Populations
requestBody:
required: true
content:
application/json:
schema:
description: Create a Population
type: object
properties:
name:
type: string
minLength: 1
description:
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. When
omitted, it defaults to the requesting member: a personal
access token's owner, or the member an organization API key
assumes. An organization API key acting as itself must send
it, or the request fails with a 400.
type: string
projects:
type: array
items:
type: string
datasource:
description: Id of the Data Source
type: string
userIdTypes:
description: >-
Identifier types the Population can be joined on. Every
step's fact table must support all of them
minItems: 1
type: array
items:
type: string
steps:
description: >-
Steps a unit must complete, in order, to be included.
Currently limited to 1 step with support for multiple steps
coming soon.
minItems: 1
maxItems: 1
type: array
items:
type: object
properties:
source:
anyOf:
- type: object
properties:
type:
type: string
const: factTable
factTableId:
type: string
required:
- type
- factTableId
additionalProperties: false
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
aggregateFilter:
description: >-
Conditions on each unit's total within the queried
date range, such as ">=3" or ">=3,<10". Requires
aggregateFilterColumn
type: string
aggregateFilterColumn:
description: >-
Numeric column to total, or "$$count" to count rows.
Requires aggregateFilter
type: string
required:
- source
additionalProperties: false
required:
- name
- datasource
- userIdTypes
- steps
additionalProperties: false
responses:
'200':
description: Resource created
content:
application/json:
schema:
type: object
properties:
population:
$ref: '#/components/schemas/Population'
required:
- population
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X POST 'https://api.growthbook.io/api/v1/populations' \
-H 'Authorization: Bearer YOUR_API_KEY'
/v1/populations/{id}:
get:
operationId: getPopulation
summary: Get a single population
tags:
- Populations
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
population:
$ref: '#/components/schemas/Population'
required:
- population
additionalProperties: false
x-codeSamples:
- lang: cURL
source: |-
curl -X GET 'https://api.growthbook.io/api/v1/populations/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
put:
operationId: updatePopulation
summary: Update a single population
tags:
- Populations
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
description: Update a Population
type: object
properties:
name:
type: string
minLength: 1
description:
type: string
projects:
type: array
items:
type: string
userIdTypes:
description: >-
Identifier types the Population can be joined on. Every
step's fact table must support all of them
minItems: 1
type: array
items:
type: string
steps:
description: >-
Steps a unit must complete, in order, to be included.
Currently limited to 1 step with support for multiple steps
coming soon.
minItems: 1
maxItems: 1
type: array
items:
type: object
properties:
source:
anyOf:
- type: object
properties:
type:
type: string
const: factTable
factTableId:
type: string
required:
- type
- factTableId
additionalProperties: false
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
aggregateFilter:
description: >-
Conditions on each unit's total within the queried
date range, such as ">=3" or ">=3,<10". Requires
aggregateFilterColumn
type: string
aggregateFilterColumn:
description: >-
Numeric column to total, or "$$count" to count rows.
Requires aggregateFilter
type: string
required:
- source
additionalProperties: false
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
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
type: object
properties:
population:
$ref: '#/components/schemas/Population'
required:
- population
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X PUT 'https://api.growthbook.io/api/v1/populations/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
delete:
operationId: deletePopulation
summary: Delete a single population
tags:
- Populations
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
description: Resource deleted
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
'202':
$ref: '#/components/responses/ConfirmationHeld'
x-codeSamples:
- lang: cURL
source: |-
curl -X DELETE 'https://api.growthbook.io/api/v1/populations/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'
components:
parameters:
limit:
name: limit
in: query
description: The number of items to return
schema:
default: 10
description: The number of items to return
type: integer
minimum: 1
maximum: 100
offset:
name: offset
in: query
description: How many items to skip (use in conjunction with limit for pagination)
schema:
default: 0
description: How many items to skip (use in conjunction with limit for pagination)
type: integer
minimum: 0
projectId:
name: projectId
in: query
description: Filter by project id
schema:
description: Filter by project id
type: string
clientKey:
name: clientKey
in: query
description: Filter by a SDK connection's client key
schema:
description: Filter by a SDK connection's client key
type: string
skipPagination:
name: skipPagination
in: query
description: >-
If true, return all matching items and ignore limit/offset.
Self-hosted only. Has no effect unless API_ALLOW_SKIP_PAGINATION is set
to true or 1.
schema:
description: >-
If true, return all matching items and ignore limit/offset.
Self-hosted only. Has no effect unless API_ALLOW_SKIP_PAGINATION is
set to true or 1.
default: false
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
x-selfHostedOnly: true
x-requiresEnv: API_ALLOW_SKIP_PAGINATION
id:
name: id
in: path
required: true
description: The id of the requested resource
schema:
description: The id of the requested resource
type: string
withRevisions:
name: withRevisions
in: query
description: Also return feature revisions (all, draft, or published statuses)
schema:
description: Also return feature revisions (all, draft, or published statuses)
type: string
enum:
- all
- drafts
- published
- none
ids:
name: ids
in: query
required: true
description: >
Comma-separated list of feature IDs (URL-encoded if needed). Example:
`my_feature,another_feature`
schema:
description: >
Comma-separated list of feature IDs (URL-encoded if needed). Example:
`my_feature,another_feature`
type: string
featureId:
name: featureId
in: query
description: ''
schema:
type: string
status:
name: status
in: query
description: >-
Filter by revision status. Single value, comma-separated list, repeated
params (?status=draft&status=approved), or `all-drafts` shorthand for
all active-draft statuses (draft, pending-review, approved,
changes-requested).
schema:
description: >-
Filter by revision status. Single value, comma-separated list,
repeated params (?status=draft&status=approved), or `all-drafts`
shorthand for all active-draft statuses (draft, pending-review,
approved, changes-requested).
anyOf:
- type: string
- type: array
items:
type: string
author:
name: author
in: query
description: ''
schema:
type: string
mine:
name: mine
in: query
description: >-
If true, return only revisions authored by or contributed to by the
calling user. Needs a personal access token, or an organization API key
that assumes a named member's role. Mutually exclusive with `author`.
schema:
description: >-
If true, return only revisions authored by or contributed to by the
calling user. Needs a personal access token, or an organization API
key that assumes a named member's role. Mutually exclusive with
`author`.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
version:
name: version
in: path
required: true
description: ''
schema:
type: integer
overrideDraftLimit:
name: overrideDraftLimit
in: query
description: >-
If the organization caps concurrent drafts per feature
(`maxConcurrentDrafts` setting), requests at or over the cap are
rejected with a 409. Pass `true` to create the draft anyway. 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.
schema:
description: >-
If the organization caps concurrent drafts per feature
(`maxConcurrentDrafts` setting), requests at or over the cap are
rejected with a 409. Pass `true` to create the draft anyway. 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.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
ruleId:
name: ruleId
in: path
required: true
description: ''
schema:
type: string
archived:
name: archived
in: query
description: >-
Whether to include archived features. Defaults to `false` (non-archived
only). Pass `true` to include archived features alongside non-archived
ones.
schema:
description: >-
Whether to include archived features. Defaults to `false`
(non-archived only). Pass `true` to include archived features
alongside non-archived ones.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
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
format:
name: format
in: query
description: >-
`minimal` (default) returns only what changed, with id-keyed arrays
bucketed into added/removed/modified items. `full` returns the complete
before/after content of the revision.
schema:
description: >-
`minimal` (default) returns only what changed, with id-keyed arrays
bucketed into added/removed/modified items. `full` returns the
complete before/after content of the revision.
type: string
enum:
- minimal
- full
base:
name: base
in: query
description: >-
Compare against: `baseVersion` (default — the revision's own
`baseVersion`, matches the in-app review view), `live` (the
currently-live revision), or an integer version (an arbitrary historical
revision).
schema:
description: >-
Compare against: `baseVersion` (default — the revision's own
`baseVersion`, matches the in-app review view), `live` (the
currently-live revision), or an integer version (an arbitrary
historical revision).
anyOf:
- type: string
const: baseVersion
- type: string
const: live
- type: integer
logId:
name: logId
in: path
required: true
description: ''
schema:
type: string
datasourceId:
name: datasourceId
in: query
description: Filter by Data Source
schema:
description: Filter by Data Source
type: string
trackingKey:
name: trackingKey
in: query
description: Filter by experiment tracking key
schema:
description: Filter by experiment tracking key
type: string
experimentId:
name: experimentId
in: query
description: >-
Filter the returned list by the experiment tracking key (not the
internal experiment ID). Note, this was deprecated to help reduce
confusion, consider using `trackingKey` instead, which is functionally
identical. You cannot use both params at the same time.
schema:
deprecated: true
description: >-
Filter the returned list by the experiment tracking key (not the
internal experiment ID). Note, this was deprecated to help reduce
confusion, consider using `trackingKey` instead, which is functionally
identical. You cannot use both params at the same time.
type: string
q:
name: q
in: query
description: >-
Raw experiment search/filter string (same syntax as the app's experiment
list filters, e.g. `status:running tag:checkout`). Negation (`!`) and
operators (`~`, `^`, `>`, `<`, `=`) are not supported and return a 400
schema:
description: >-
Raw experiment search/filter string (same syntax as the app's
experiment list filters, e.g. `status:running tag:checkout`). Negation
(`!`) and operators (`~`, `^`, `>`, `<`, `=`) are not supported and
return a 400
type: string
owner:
name: owner
in: query
description: Filter by comma-separated owner ids, names, or emails
schema:
description: Filter by comma-separated owner ids, names, or emails
type: string
result:
name: result
in: query
description: >-
Filter by comma-separated results (won, lost, inconclusive, dnf).
Matches the experiment's recorded result — set when an experiment is
stopped and retained if it's later restarted, so running experiments can
match too
schema:
description: >-
Filter by comma-separated results (won, lost, inconclusive, dnf).
Matches the experiment's recorded result — set when an experiment is
stopped and retained if it's later restarted, so running experiments
can match too
type: array
items:
type: string
enum:
- dnf
- won
- lost
- inconclusive
explode: false
tag:
name: tag
in: query
description: Filter by comma-separated tags
schema:
description: Filter by comma-separated tags
type: string
implementationType:
name: implementationType
in: query
description: >-
Filter by comma-separated implementation types (feature, visualChange,
redirect) — the kinds of changes linked to the experiment. To filter
standard experiments vs bandits, use `bandits` instead
schema:
description: >-
Filter by comma-separated implementation types (feature, visualChange,
redirect) — the kinds of changes linked to the experiment. To filter
standard experiments vs bandits, use `bandits` instead
type: array
items:
type: string
enum:
- feature
- visualChange
- redirect
explode: false
metricId:
name: metricId
in: query
description: >-
Filter by comma-separated metric ids. Matches experiments that use a
metric as a goal, secondary, or guardrail metric
schema:
description: >-
Filter by comma-separated metric ids. Matches experiments that use a
metric as a goal, secondary, or guardrail metric
type: string
bandits:
name: bandits
in: query
description: When true, return only multi-armed bandits; when false, exclude them
schema:
description: When true, return only multi-armed bandits; when false, exclude them
type: string
enum:
- 'true'
- 'false'
sortBy:
name: sortBy
in: query
description: Field to sort the results by
schema:
default: dateCreated
description: Field to sort the results by
type: string
enum:
- dateCreated
- dateUpdated
- name
sortOrder:
name: sortOrder
in: query
description: Sort direction (used with `sortBy`)
schema:
default: asc
description: Sort direction (used with `sortBy`)
type: string
enum:
- asc
- desc
phase:
name: phase
in: query
description: ''
schema:
type: string
dimension:
name: dimension
in: query
description: ''
schema:
type: string
linkedChanges:
name: linkedChanges
in: query
description: >-
Required while the experiment still serves through linked changes.
"materialize" keeps a stopped experiment's released variation as a
permanent force rule on each linked Feature Flag; "remove" acknowledges
that the linked changes stop serving.
schema:
description: >-
Required while the experiment still serves through linked changes.
"materialize" keeps a stopped experiment's released variation as a
permanent force rule on each linked Feature Flag; "remove"
acknowledges that the linked changes stop serving.
type: string
enum:
- materialize
- remove
variationId:
name: variationId
in: path
required: true
description: ''
schema:
type: string
snapshotId:
name: snapshotId
in: path
required: true
description: The snapshot id
schema:
description: The snapshot id
type: string
eventId:
name: eventId
in: path
required: true
description: The event id
schema:
description: The event id
type: string
autoPublish:
name: autoPublish
in: query
description: >-
Publish the resulting revision immediately instead of leaving it as a
draft.
schema:
description: >-
Publish the resulting revision immediately instead of leaving it as a
draft.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
draftVersion:
name: draftVersion
in: query
description: >-
Remove the rule from this existing draft revision instead of live.
Required when the rule hasn't been published yet — omitting it targets
the live revision, which has nothing to remove.
schema:
description: >-
Remove the rule from this existing draft revision instead of live.
Required when the rule hasn't been published yet — omitting it targets
the live revision, which has nothing to remove.
type: integer
includeArchived:
name: includeArchived
in: query
description: >-
Whether to include archived metrics. Defaults to `true`. Pass `false` to
return only non-archived metrics.
schema:
description: >-
Whether to include archived metrics. Defaults to `true`. Pass `false`
to return only non-archived metrics.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
type:
name: type
in: query
description: >-
Filter by comma-separated experiment types (feature, visualChange,
redirect)
schema:
description: >-
Filter by comma-separated experiment types (feature, visualChange,
redirect)
type: string
startDate:
name: startDate
in: query
description: >-
Only include experiments that have a phase which ended on or after this
date
schema:
description: >-
Only include experiments that have a phase which ended on or after
this date
type: string
endDate:
name: endDate
in: query
description: >-
Only include experiments that have a phase which ended on or before this
date
schema:
description: >-
Only include experiments that have a phase which ended on or before
this date
type: string
property:
name: property
in: path
required: true
description: The attribute property
schema:
description: The attribute property
type: string
withProxy:
name: withProxy
in: query
description: ''
schema:
type: string
multiOrg:
name: multiOrg
in: query
description: ''
schema:
type: string
key:
name: key
in: path
required: true
description: The key of the requested sdkConnection
schema:
description: The key of the requested sdkConnection
type: string
dataSourceId:
name: dataSourceId
in: path
required: true
description: The id of the data source
schema:
description: The id of the data source
type: string
includeExperiment:
name: includeExperiment
in: query
description: Include the associated experiment in payload
schema:
description: Include the associated experiment in payload
type: integer
visualChangeId:
name: visualChangeId
in: path
required: true
description: Specify a specific visual change
schema:
description: Specify a specific visual change
type: string
savedGroupId:
name: savedGroupId
in: query
description: >-
Restrict results to revisions for a single saved group. When omitted,
returns revisions across every saved group the caller can read.
schema:
description: >-
Restrict results to revisions for a single saved group. When omitted,
returns revisions across every saved group the caller can read.
type: string
effective:
name: effective
in: query
description: >-
When true, includes fields inherited across the lineage (the family's
accumulated schema). When false (default), returns only this config's
own fields.
schema:
description: >-
When true, includes fields inherited across the lineage (the family's
accumulated schema). When false (default), returns only this config's
own fields.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: boolean
source:
name: source
in: query
description: >-
Render using a previously-captured source projection (its named types).
Only affects the typed-code formats
(`typescript`/`protobuf`/`python`/`go`/`rust`); ignored if the source
has no projection.
schema:
description: >-
Render using a previously-captured source projection (its named
types). Only affects the typed-code formats
(`typescript`/`protobuf`/`python`/`go`/`rust`); ignored if the source
has no projection.
type: string
search:
name: search
in: query
description: >-
Search string to search organization names, owner emails, and external
ids by
schema:
description: >-
Search string to search organization names, owner emails, and external
ids by
type: string
factTableId:
name: factTableId
in: path
required: true
description: Specify a specific fact table
schema:
description: Specify a specific fact table
type: string
idType:
name: idType
in: query
description: >-
Only return runs for this id type. When omitted, runs for all id types
are returned.
schema:
description: >-
Only return runs for this id type. When omitted, runs for all id types
are returned.
type: string
runId:
name: runId
in: path
required: true
description: The id of the aggregated table run (e.g. aftr_...)
schema:
description: The id of the aggregated table run (e.g. aftr_...)
type: string
deleteMissing:
name: deleteMissing
in: query
description: >-
Whether to delete code references that are no longer present in the
submitted data
schema:
description: >-
Whether to delete code references that are no longer present in the
submitted data
default: 'false'
type: string
enum:
- 'true'
- 'false'
userName:
name: userName
in: query
description: Name of the user.
schema:
description: Name of the user.
type: string
userEmail:
name: userEmail
in: query
description: Email address of the user.
schema:
description: Email address of the user.
type: string
globalRole:
name: globalRole
in: query
description: Name of the global role
schema:
description: Name of the global role
type: string
wait:
name: wait
in: query
description: Seconds to wait for a decision before responding, up to 30
schema:
description: Seconds to wait for a decision before responding, up to 30
type: integer
minimum: 0
maximum: 30
tableId:
name: tableId
in: path
required: true
description: The id of the information schema table
schema:
description: The id of the information schema table
type: string
environment:
name: environment
in: query
description: ''
schema:
type: string
project:
name: project
in: query
description: >-
Comma-separated Project ids. Matches ramps on Feature Flags in any of
them.
schema:
description: >-
Comma-separated Project ids. Matches ramps on Feature Flags in any of
them.
type: array
items:
type: string
explode: false
feature:
name: feature
in: query
description: Comma-separated Feature Flag ids.
schema:
description: Comma-separated Feature Flag ids.
type: array
items:
type: string
explode: false
customFields:
name: customFields
in: query
description: >-
Custom field values, as `customFields[]=`. Comma-separate
several values for one key.
schema:
description: >-
Custom field values, as `customFields[]=`. Comma-separate
several values for one key.
type: object
propertyNames:
type: string
additionalProperties:
type: array
items:
type: string
style: deepObject
explode: true
reason:
name: reason
in: query
description: >-
Used when the body has no `reason`, for tools whose payload can't be
changed.
schema:
description: >-
Used when the body has no `reason`, for tools whose payload can't be
changed.
type: string
index:
name: index
in: query
description: ''
schema:
type: string
deleteMembers:
name: deleteMembers
in: query
description: When 'true', enables deleting a team that contains members
schema:
description: When 'true', enables deleting a team that contains members
type: string
cache:
name: cache
in: query
description: >-
Controls cache behavior for this exploration: `preferred` (default)
returns a cached result if one exists, otherwise runs a new query;
`never` always runs a new query, ignoring any cached results; `required`
only returns a cached result, if none exists returns exploration: null
with a message
schema:
description: >-
Controls cache behavior for this exploration: `preferred` (default)
returns a cached result if one exists, otherwise runs a new query;
`never` always runs a new query, ignoring any cached results;
`required` only returns a cached result, if none exists returns
exploration: null with a message
type: string
enum:
- preferred
- required
- never
query:
name: query
in: query
description: ''
schema:
default: ''
type: string
maxLength: 200
skip:
name: skip
in: query
description: ''
schema:
default: 0
type: integer
minimum: 0
maximum: 10000
metricIds:
name: metricIds
in: query
description: ''
schema:
type: array
items:
type: string
minLength: 1
maxLength: 255
minItems: 1
maxItems: 20
explode: false
stage:
name: stage
in: query
description: ''
schema:
type: string
enum:
- draft
- running
- analysis-period
- stopped
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'
schemas:
FeatureV1:
type: object
properties:
id:
type: string
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
archived:
type: boolean
description:
type: string
maxLength: 10000
owner:
description: The userId 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
project:
type: string
targetingAllProjects:
type: boolean
targetingProjects:
type: array
items:
type: string
valueType:
type: string
enum:
- boolean
- string
- number
- json
defaultValue:
type: string
baseConfig:
description: >-
Key of the config backing this flag ("Config mode"), or null. The
config supplies the base JSON and schema. The internal `@config:`
directive is scrubbed from values; `@const:` references are
preserved. (v2 additionally exposes per-rule config fields.)
anyOf:
- type: string
- type: 'null'
defaultValueConfig:
description: >-
Config within `baseConfig`'s family that the default value resolves
to (a descendant), or null when the default uses `baseConfig`
directly.
anyOf:
- type: string
- type: 'null'
tags:
type: array
items:
type: string
environments:
type: object
propertyNames:
type: string
additionalProperties:
$ref: '#/components/schemas/FeatureEnvironmentV1'
prerequisites:
description: Feature IDs. Each feature must evaluate to `true`
type: array
items:
type: string
revision:
type: object
properties:
id:
description: Stable id of the feature's live revision.
type: string
version:
type: integer
comment:
type: string
date:
format: date-time
type: string
createdBy:
type: string
publishedBy:
type: string
required:
- version
- comment
- date
- createdBy
- publishedBy
additionalProperties: false
customFields:
type: object
propertyNames:
type: string
additionalProperties: {}
holdout:
anyOf:
- type: object
properties:
id:
description: Holdout ID
type: string
value:
description: >-
The feature value assigned to users in the holdout treatment
group
type: string
required:
- id
- value
additionalProperties: false
- type: 'null'
required:
- id
- dateCreated
- dateUpdated
- archived
- description
- owner
- project
- valueType
- defaultValue
- tags
- environments
- revision
additionalProperties: false
FeatureEnvironmentV1:
type: object
properties:
enabled:
type: boolean
defaultValue:
type: string
rules:
type: array
items:
$ref: '#/components/schemas/FeatureRuleV1'
definition:
description: A JSON stringified [FeatureDefinition](#tag/FeatureDefinition_model)
type: string
draft:
type: object
properties:
enabled:
type: boolean
defaultValue:
type: string
rules:
type: array
items:
$ref: '#/components/schemas/FeatureRuleV1'
definition:
description: >-
A JSON stringified
[FeatureDefinition](#tag/FeatureDefinition_model)
type: string
required:
- enabled
- defaultValue
- rules
additionalProperties: false
required:
- enabled
- defaultValue
- rules
additionalProperties: false
FeatureRuleV1:
anyOf:
- title: Feature Force Rule
$ref: '#/components/schemas/FeatureForceRule'
- title: Feature Rollout Rule
$ref: '#/components/schemas/FeatureRolloutRule'
- title: Feature Experiment Rule
$ref: '#/components/schemas/FeatureExperimentRule'
- title: Feature Experiment Ref Rule
$ref: '#/components/schemas/FeatureExperimentRefRule'
- title: Feature Contextual Bandit Ref Rule
$ref: '#/components/schemas/FeatureContextualBanditRefRule'
- title: Feature Safe Rollout Rule
$ref: '#/components/schemas/FeatureSafeRolloutRule'
FeatureForceRule:
allOf:
- description: >
Common fields shared by all feature rule types. Specific rule types
extend
this base with their own required properties (value, coverage,
etc.).
type: object
properties:
description:
type: string
maxLength: 10000
condition:
type: string
id:
type: string
enabled:
type: boolean
scheduleRules:
description: Simple time-based on/off schedule for this rule
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
scheduleType:
description: >
UI hint for which scheduling mode is active:
- `none` – no schedule
- `schedule` – simple time-based enable/disable via
`scheduleRules`
- `ramp` – multi-step ramp-up controlled by an associated
RampSchedule document
type: string
enum:
- none
- schedule
- ramp
rampScheduleId:
description: >-
ID of the active RampSchedule document controlling this rule.
Present when `scheduleType` is `ramp` and a live schedule
exists.
type: string
savedGroupTargeting:
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID of the prerequisite
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
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
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
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
fallbackAttribute:
description: >-
Used in place of `hashAttribute` when a user lacks it. Only SDKs
with Sticky Bucketing enabled use it.
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
FeatureExperimentRefRule:
allOf:
- description: >
Common fields shared by all feature rule types. Specific rule types
extend
this base with their own required properties (value, coverage,
etc.).
type: object
properties:
description:
type: string
maxLength: 10000
condition:
type: string
id:
type: string
enabled:
type: boolean
scheduleRules:
description: Simple time-based on/off schedule for this rule
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
scheduleType:
description: >
UI hint for which scheduling mode is active:
- `none` – no schedule
- `schedule` – simple time-based enable/disable via
`scheduleRules`
- `ramp` – multi-step ramp-up controlled by an associated
RampSchedule document
type: string
enum:
- none
- schedule
- ramp
rampScheduleId:
description: >-
ID of the active RampSchedule document controlling this rule.
Present when `scheduleType` is `ramp` and a live schedule
exists.
type: string
savedGroupTargeting:
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID of the prerequisite
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
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-ref
variations:
type: array
items:
type: object
properties:
value:
type: string
variationId:
type: string
required:
- value
- variationId
additionalProperties: false
experimentId:
type: string
sparse:
description: >-
JSON features only. When true, each variation `value` is a
partial object merged onto the feature's default value instead
of replacing it.
type: boolean
required:
- type
- variations
- experimentId
additionalProperties: false
FeatureContextualBanditRefRule:
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: contextual-bandit-ref
variations:
type: array
items:
type: object
properties:
value:
type: string
variationId:
type: string
required:
- value
- variationId
additionalProperties: false
contextualBanditId:
type: string
required:
- type
- variations
- contextualBanditId
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
PaginationFields:
type: object
properties:
limit:
type: integer
offset:
type: integer
count:
type: integer
total:
type: integer
hasMore:
type: boolean
nextOffset:
anyOf:
- type: integer
- type: 'null'
required:
- limit
- offset
- count
- total
- hasMore
- nextOffset
additionalProperties: false
FeatureWithRevisionsV1:
allOf:
- $ref: '#/components/schemas/FeatureV1'
- type: object
properties:
revisions:
type: array
items:
$ref: '#/components/schemas/FeatureRevisionV1'
additionalProperties: false
FeatureRevisionV1:
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:
type: string
publishedBy:
type: string
defaultValue:
description: The default value at the time this revision was created
type: string
rules:
type: object
propertyNames:
type: string
additionalProperties:
type: array
items:
$ref: '#/components/schemas/FeatureRuleV1'
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
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
prerequisites:
description: >-
Feature-level prerequisites captured in this revision (only present
when prerequisite gating is enabled)
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
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:
- type: string
format: date-time
- type: 'null'
cutoffDate:
description: >-
ISO 8601 date-time, e.g. "2025-07-01T00:00:00Z". The ramp
ends at this time.
anyOf:
- type: string
format: date-time
- 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:
- type: string
format: date-time
- type: 'null'
cutoffDate:
description: >-
ISO 8601 date-time, e.g. "2025-07-01T00:00:00Z". The ramp
ends at this time.
anyOf:
- type: string
format: date-time
- 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
required:
- id
- featureId
- baseVersion
- version
- comment
- date
- status
- rules
additionalProperties: false
FeatureV2:
type: object
properties:
id:
type: string
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
archived:
type: boolean
description:
type: string
maxLength: 10000
owner:
description: >-
The userId or email address of the owner. If an email address is
provided, it will be used to look up the userId of the matching
organization member. If an ID is provided, it will be validated as
existing in the organization.
type: string
project:
type: string
targetingAllProjects:
type: boolean
targetingProjects:
type: array
items:
type: string
valueType:
type: string
enum:
- boolean
- string
- number
- json
defaultValue:
type: string
baseConfig:
description: >-
Key of the config backing this flag ("Config mode"). Requires
`valueType: "json"` and a live config. The config supplies the base
JSON and schema; `defaultValue` and rule values are override patches
on top. null or omitted for a plain flag.
anyOf:
- type: string
- type: 'null'
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'
tags:
type: array
items:
type: string
rules:
description: >-
Unified rules array. Each rule carries its own environment scope via
`allEnvironments` / `environments`.
type: array
items:
$ref: '#/components/schemas/FeatureRuleV2'
environments:
description: >-
Per-environment enabled state and SDK payload. Rules are on the
top-level `rules` field.
type: object
propertyNames:
type: string
additionalProperties:
$ref: '#/components/schemas/FeatureEnvironmentV2'
prerequisites:
description: Feature IDs. Each feature must evaluate to `true`
type: array
items:
type: string
revision:
$ref: '#/components/schemas/FeatureRevisionSummary'
customFields:
type: object
propertyNames:
type: string
additionalProperties: {}
holdout:
anyOf:
- type: object
properties:
id:
description: Holdout ID
type: string
value:
description: >-
The feature value assigned to users in the holdout treatment
group
type: string
required:
- id
- value
additionalProperties: false
- type: 'null'
required:
- id
- dateCreated
- dateUpdated
- archived
- description
- owner
- project
- valueType
- defaultValue
- tags
- rules
- environments
- revision
additionalProperties: false
FeatureRuleV2:
allOf:
- 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
- title: Feature Experiment Rule
$ref: '#/components/schemas/FeatureExperimentRule'
- 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
- title: Feature Safe Rollout Rule
$ref: '#/components/schemas/FeatureSafeRolloutRule'
- 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
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
FeatureEnvironmentV2:
type: object
properties:
enabled:
type: boolean
defaultValue:
type: string
definition:
description: A JSON stringified [FeatureDefinition](#tag/FeatureDefinition_model)
type: string
required:
- enabled
- defaultValue
additionalProperties: false
FeatureRevisionSummary:
type: object
properties:
id:
description: Stable id of the feature's live revision.
type: string
version:
type: integer
comment:
type: string
date:
format: date-time
type: string
createdBy:
$ref: '#/components/schemas/EventUser'
publishedBy:
$ref: '#/components/schemas/EventUser'
required:
- version
- comment
- date
additionalProperties: false
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
FeatureWithRevisionsV2:
allOf:
- $ref: '#/components/schemas/FeatureV2'
- type: object
properties:
revisions:
type: array
items:
$ref: '#/components/schemas/FeatureRevisionV2'
additionalProperties: false
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:
- type: string
format: date-time
- type: 'null'
cutoffDate:
description: >-
ISO 8601 date-time, e.g. "2025-07-01T00:00:00Z". The ramp
ends at this time.
anyOf:
- type: string
format: date-time
- 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:
- type: string
format: date-time
- type: 'null'
cutoffDate:
description: >-
ISO 8601 date-time, e.g. "2025-07-01T00:00:00Z". The ramp
ends at this time.
anyOf:
- type: string
format: date-time
- 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:
description: Who armed the deferred publish, with an API key's name
$ref: '#/components/schemas/EventUser'
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
Targeting Rule:
description: >-
A targeting rule that serves a specific value to users matching the
conditions. Set coverage < 1 for a percentage rollout.
type: object
properties:
description:
description: Short note on why the rule exists (e.g. `Beta testers only`).
type: string
enabled:
type: boolean
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
allEnvironments:
description: >-
When true the rule applies to all environments. Omit both scope
fields to apply to all environments.
type: boolean
environments:
description: >-
Environment IDs the rule applies to. Ignored when allEnvironments is
true; with allEnvironments false, an omitted or empty list scopes
the rule to no environment.
type: array
items:
type: string
type:
description: >-
Use "force" for a standard targeting rule, or "rollout" for a
percentage rollout (coverage < 1). Defaults to "force". Both are
functionally equivalent; a force rule with coverage < 1 behaves as a
rollout.
type: string
enum:
- force
- rollout
value:
description: The value to serve when this rule matches.
type: string
config:
description: >-
Key of a config to back this value. When set, `value` is a JSON
override patch merged on top of the config; omit or null for a plain
value.
anyOf:
- type: string
- type: 'null'
sparse:
description: >-
JSON features only. When true, the rule value is a partial object
merged onto the feature's default value instead of replacing it.
type: boolean
coverage:
description: >-
Percentage of users to include (0–1). Defaults to 1. When less than
1, hashAttribute is required.
type: number
minimum: 0
maximum: 1
hashAttribute:
description: >-
Attribute to hash on for consistent assignment. Required when
coverage < 1.
type: string
fallbackAttribute:
description: >-
Used in place of `hashAttribute` when a user lacks it. Only SDKs
with Sticky Bucketing enabled use it.
type: string
seed:
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:
- value
additionalProperties: false
Experiment Rule:
description: An experiment rule that links a feature value to an existing experiment.
type: object
properties:
description:
description: Short note on why the rule exists (e.g. `Beta testers only`).
type: string
enabled:
type: boolean
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
allEnvironments:
description: >-
When true the rule applies to all environments. Omit both scope
fields to apply to all environments.
type: boolean
environments:
description: >-
Environment IDs the rule applies to. Ignored when allEnvironments is
true; with allEnvironments false, an omitted or empty list scopes
the rule to no environment.
type: array
items:
type: string
type:
description: Must be "experiment-ref" for an experiment rule.
type: string
const: experiment-ref
experimentId:
description: ID of the linked experiment.
type: string
variations:
type: array
items:
type: object
properties:
variationId:
type: string
value:
type: string
config:
description: >-
Key of a config to back this variation value. When set,
`value` is a JSON override patch merged on top of the config;
omit or null for a plain value.
anyOf:
- type: string
- type: 'null'
required:
- value
additionalProperties: false
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
- experimentId
- variations
additionalProperties: false
Safe Rollout Rule:
description: >-
A safe rollout rule with automated guardrail monitoring and optional
auto-rollback.
type: object
properties:
description:
description: Short note on why the rule exists (e.g. `Beta testers only`).
type: string
enabled:
type: boolean
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
allEnvironments:
description: >-
When true the rule applies to all environments. Omit both scope
fields to apply to all environments.
type: boolean
environments:
description: >-
Environment IDs the rule applies to. Ignored when allEnvironments is
true; with allEnvironments false, an omitted or empty list scopes
the rule to no environment.
type: array
items:
type: string
type:
description: Must be "safe-rollout" for a safe rollout rule.
type: string
const: safe-rollout
controlValue:
type: string
variationValue:
type: string
hashAttribute:
type: string
trackingKey:
type: string
seed:
type: string
safeRolloutFields:
type: object
properties:
datasourceId:
type: string
exposureQuery:
description: >-
The assignment query, grouping its ID with the identifier type
analyzed on. Mutually exclusive with the deprecated
`exposureQueryId`.
type: object
properties:
id:
description: The ID of one of the data source's assignment queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the query must
declare. Required when selecting a different assignment
query that declares several. Otherwise defaults to the
current identifier type, or the query's only one. Null is
treated as omitted, so a response's value can be sent back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
exposureQueryId:
deprecated: true
description: >-
Deprecated: use `exposureQuery`. Rejected when selecting a
different assignment query that declares several identifier
types; set `exposureQuery.identifierType` instead.
type: string
guardrailMetricIds:
minItems: 1
type: array
items:
type: string
maxDuration:
type: object
properties:
amount:
type: number
exclusiveMinimum: 0
unit:
type: string
enum:
- weeks
- days
- hours
- minutes
required:
- amount
- unit
additionalProperties: false
autoRollback:
type: boolean
rampUpSchedule:
type: object
properties:
enabled:
type: boolean
steps:
minItems: 1
type: array
items:
type: object
properties:
percent:
type: number
minimum: 0
maximum: 1
required:
- percent
additionalProperties: false
required:
- enabled
additionalProperties: false
required:
- datasourceId
- guardrailMetricIds
- maxDuration
additionalProperties: false
required:
- type
- controlValue
- variationValue
- hashAttribute
- safeRolloutFields
additionalProperties: false
Archetype:
type: object
properties:
id:
type: string
dateCreated:
type: string
dateUpdated:
type: string
name:
type: string
description:
type: string
maxLength: 10000
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
isPublic:
type: boolean
attributes:
description: The attributes to set when using this Archetype
type: object
propertyNames:
type: string
additionalProperties: {}
projects:
type: array
items:
type: string
environments:
description: >-
Limit this Archetype to specific environments. Omit or leave empty
to apply to all environments.
type: array
items:
type: string
required:
- id
- dateCreated
- dateUpdated
- name
- owner
- isPublic
- attributes
additionalProperties: false
Experiment:
type: object
properties:
id:
type: string
trackingKey:
type: string
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
name:
type: string
type:
type: string
enum:
- standard
- multi-armed-bandit
- holdout
project:
type: string
hypothesis:
type: string
description:
type: string
maxLength: 10000
tags:
type: array
items:
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
archived:
type: boolean
status:
type: string
autoRefresh:
type: boolean
hashAttribute:
type: string
fallbackAttribute:
type: string
hashVersion:
anyOf:
- type: number
const: 1
- type: number
const: 2
disableStickyBucketing:
type: boolean
bucketVersion:
type: number
minBucketVersion:
type: number
variations:
type: array
items:
type: object
properties:
variationId:
type: string
key:
type: string
name:
type: string
description:
type: string
maxLength: 10000
screenshots:
type: array
items:
type: string
required:
- variationId
- key
- name
- description
- screenshots
additionalProperties: false
phases:
type: array
items:
type: object
properties:
name:
type: string
dateStarted:
type: string
dateEnded:
type: string
reasonForStopping:
type: string
seed:
type: string
coverage:
type: number
trafficSplit:
type: array
items:
type: object
properties:
variationId:
type: string
weight:
type: number
required:
- variationId
- weight
additionalProperties: false
namespace:
type: object
properties:
namespaceId:
type: string
enabled:
type: boolean
range:
minItems: 2
maxItems: 2
type: array
items:
type: number
ranges:
type: array
items:
type: array
prefixItems:
- type: number
- type: number
required:
- namespaceId
additionalProperties: false
targetingCondition:
type: string
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
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
required:
- name
- dateStarted
- dateEnded
- reasonForStopping
- seed
- coverage
- trafficSplit
- targetingCondition
additionalProperties: false
settings:
$ref: '#/components/schemas/ExperimentAnalysisSettings'
resultSummary:
type: object
properties:
status:
type: string
winner:
type: string
conclusions:
type: string
releasedVariationId:
type: string
excludeFromPayload:
type: boolean
required:
- status
- winner
- conclusions
- releasedVariationId
- excludeFromPayload
additionalProperties: false
shareLevel:
type: string
enum:
- public
- organization
publicUrl:
type: string
banditScheduleValue:
type: number
banditScheduleUnit:
type: string
enum:
- days
- hours
banditBurnInValue:
type: number
banditBurnInUnit:
type: string
enum:
- days
- hours
banditConversionWindowValue:
type: number
banditConversionWindowUnit:
type: string
enum:
- days
- hours
linkedFeatures:
type: array
items:
type: string
attributeScopeAllProjects:
type: boolean
hasVisualChangesets:
type: boolean
hasURLRedirects:
type: boolean
customFields:
type: object
propertyNames:
type: string
additionalProperties: {}
customMetricSlices:
description: Custom slices that apply to ALL applicable metrics in the experiment
type: array
items:
type: object
properties:
slices:
type: array
items:
type: object
properties:
column:
type: string
levels:
type: array
items:
type: string
required:
- column
- levels
additionalProperties: false
required:
- slices
additionalProperties: false
precomputedUnitDimensionIds:
maxItems: 3
type: array
items:
type: string
defaultDashboardId:
description: ID of the default dashboard for this experiment.
type: string
templateId:
type: string
statusUpdateSchedule:
anyOf:
- description: >-
Scheduled start/end for an experiment. All fields optional; the
end may be an absolute `stopAt` or a deferred relative
`stopAfter`, but not both.
type: object
properties:
startAt:
description: >-
ISO datetime when the experiment should start. Must be in
the future. Setting or clearing this field invalidates any
existing staged start (`nextScheduledStatusUpdate`); call
POST /experiments/{id}/start to stage the new schedule.
format: date-time
type: string
stopAt:
description: >-
ISO datetime when the experiment should stop. Resolved from
`stopAfter` at start when a relative end was set.
format: date-time
type: string
stopAfter:
description: >-
Relative end offset. Deferred: resolved to a concrete
`stopAt` at the experiment's actual start (or off
`dateStarted` when already running).
type: object
properties:
value:
type: integer
exclusiveMinimum: 0
unit:
type: string
enum:
- hours
- days
required:
- value
- unit
additionalProperties: false
scheduledStopPlan:
description: >-
End-of-experiment automation applied at the scheduled end.
Required whenever a `stopAt` or `stopAfter` is set (any
mode, including `notify`).
$ref: '#/components/schemas/ScheduledStopPlan'
additionalProperties: false
- type: 'null'
nextScheduledStatusUpdate:
anyOf:
- type: object
properties:
type:
type: string
enum:
- start
- stop
date:
format: date-time
type: string
required:
- type
- date
additionalProperties: false
- type: 'null'
required:
- id
- trackingKey
- dateCreated
- dateUpdated
- name
- type
- project
- hypothesis
- description
- tags
- owner
- archived
- status
- autoRefresh
- hashAttribute
- hashVersion
- variations
- phases
- settings
additionalProperties: false
ExperimentAnalysisSettings:
type: object
properties:
datasourceId:
type: string
assignmentQuery:
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
assignmentQueryId:
description: 'Deprecated: use `assignmentQuery`.'
deprecated: true
type: string
experimentId:
type: string
segmentId:
type: string
queryFilter:
type: string
inProgressConversions:
type: string
enum:
- include
- exclude
attributionModel:
description: >-
Setting attribution model to `"experimentDuration"` is the same as
selecting "Ignore Conversion Windows" for the Conversion Window
Override. Setting it to `"lookbackOverride"` requires a
`lookbackOverride` object to be provided.
type: string
enum:
- firstExposure
- experimentDuration
- lookbackOverride
lookbackOverride:
$ref: '#/components/schemas/LookbackOverride'
statsEngine:
type: string
enum:
- bayesian
- frequentist
regressionAdjustmentEnabled:
type: boolean
sequentialTestingEnabled:
type: boolean
sequentialTestingTuningParameter:
type: number
postStratificationEnabled:
description: When null, the organization default is used.
anyOf:
- description: When null, the organization default is used.
type: boolean
- description: When null, the organization default is used.
type: 'null'
decisionFrameworkSettings:
description: >-
Controls the decision framework and metric overrides for the
experiment. Replaces the entire stored object on update (does not
patch individual fields).
$ref: '#/components/schemas/ExperimentDecisionFrameworkSettings'
metricOverrides:
description: >-
Per-metric analysis overrides; also reflected in
goals/secondaryMetrics/guardrails overrides when applicable. On
create/update, this replaces the entire stored array (it does not
patch individual entries).
type: array
items:
$ref: '#/components/schemas/ExperimentMetricOverrideEntry'
goals:
type: array
items:
$ref: '#/components/schemas/ExperimentMetric'
secondaryMetrics:
type: array
items:
$ref: '#/components/schemas/ExperimentMetric'
guardrails:
type: array
items:
$ref: '#/components/schemas/ExperimentMetric'
activationMetric:
$ref: '#/components/schemas/ExperimentMetric'
required:
- datasourceId
- assignmentQuery
- assignmentQueryId
- experimentId
- segmentId
- queryFilter
- inProgressConversions
- attributionModel
- statsEngine
- goals
- secondaryMetrics
- guardrails
additionalProperties: false
LookbackOverride:
description: >-
Controls the lookback override for the experiment. For type "window",
value must be a non-negative number and valueUnit is required.
type: object
properties:
type:
type: string
enum:
- date
- window
value:
description: >-
For "window" type - non-negative numeric value (e.g. 7 for 7 days).
For "date" type a date string.
anyOf:
- description: >-
For "window" type - non-negative numeric value (e.g. 7 for 7
days). For "date" type a date string.
type: number
- format: date-time
description: >-
For "window" type - non-negative numeric value (e.g. 7 for 7
days). For "date" type a date string.
type: string
valueUnit:
description: Used when type is "window". Defaults to "days".
type: string
enum:
- minutes
- hours
- days
- weeks
required:
- type
- value
additionalProperties: false
ExperimentDecisionFrameworkSettings:
description: >-
Controls the decision framework and metric overrides for the experiment.
Replaces the entire stored object on update (does not patch individual
fields).
type: object
properties:
decisionCriteriaId:
type: string
decisionFrameworkMetricOverrides:
type: array
items:
type: object
properties:
id:
description: ID of the metric to override settings for.
type: string
targetMDE:
description: >-
The target relative MDE to use for the metric, expressed as
proportions (e.g. use 0.1 for 10%). Must be greater than 0.
type: number
exclusiveMinimum: 0
required:
- id
additionalProperties: false
additionalProperties: false
ExperimentMetricOverrideEntry:
description: >-
Per-metric analysis overrides stored on the experiment (matches internal
metricOverrides).
type: object
properties:
id:
description: ID of the metric to override settings for.
type: string
windowType:
type: string
enum:
- conversion
- lookback
- ''
windowHours:
type: number
delayHours:
type: number
properPriorOverride:
description: >-
Must be true for the override to take effect. If true, the other
proper prior settings in this object will be used if present.
type: boolean
properPriorEnabled:
type: boolean
properPriorMean:
type: number
properPriorStdDev:
type: number
regressionAdjustmentOverride:
description: >-
Must be true for the override to take effect. If true, the other
regression adjustment settings in this object will be used if
present.
type: boolean
regressionAdjustmentEnabled:
type: boolean
regressionAdjustmentDays:
type: number
required:
- id
additionalProperties: false
ExperimentMetric:
type: object
properties:
metricId:
type: string
overrides:
type: object
properties:
delayHours:
type: number
windowHours:
type: number
window:
type: string
enum:
- conversion
- lookback
- ''
properPriorOverride:
type: boolean
properPriorEnabled:
type: boolean
properPriorMean:
type: number
properPriorStdDev:
type: number
regressionAdjustmentOverride:
type: boolean
regressionAdjustmentEnabled:
type: boolean
regressionAdjustmentDays:
type: number
winRiskThreshold:
deprecated: true
description: No longer used. Never returned.
type: number
loseRiskThreshold:
deprecated: true
description: No longer used. Never returned.
type: number
additionalProperties: false
required:
- metricId
- overrides
additionalProperties: false
ScheduledStopPlan:
description: >-
What happens at the scheduled end date. `notify` keeps the experiment
running and just notifies (soft). `auto-ship` (requires the Decision
Framework) ships the winning variation and stops; multi-winner ties
break on `tiebreakerMetricId` (higher lift); with no clear winner,
`fallback` either keeps running (`notify`) or ships
`fallbackVariationId`. `force-ship` stops and rolls out
`fallbackVariationId`. `stop` is a hard deadline that stops with no
rollout. For `force-ship` and `stop`, the Decision Framework verdict
(won/lost/inconclusive) is recorded as metadata when available.
type: object
properties:
mode:
type: string
enum:
- notify
- auto-ship
- force-ship
- stop
tiebreakerMetricId:
type: string
fallback:
description: >-
What to do at the scheduled end when there is no clear winner.
Required when `mode` is `"auto-ship"`; ignored for other modes.
type: string
enum:
- notify
- force-ship
fallbackVariationId:
type: string
required:
- mode
additionalProperties: false
ExperimentResults:
type: object
properties:
id:
type: string
dateUpdated:
type: string
experimentId:
type: string
phase:
type: string
dateStart:
type: string
dateEnd:
type: string
dimension:
type: object
properties:
type:
type: string
id:
type: string
dimensions:
type: array
items:
type: object
properties:
type:
type: string
id:
type: string
required:
- type
additionalProperties: false
required:
- type
additionalProperties: false
settings:
$ref: '#/components/schemas/ExperimentAnalysisSettings'
queryIds:
type: array
items:
type: string
results:
type: array
items:
type: object
properties:
dimension:
type: string
totalUsers:
type: number
checks:
type: object
properties:
srm:
type: number
required:
- srm
additionalProperties: false
metrics:
type: array
items:
type: object
properties:
metricId:
type: string
metricName:
type: string
variations:
type: array
items:
type: object
properties:
variationId:
type: string
variationName:
type: string
users:
type: number
analyses:
type: array
items:
type: object
properties:
engine:
type: string
enum:
- bayesian
- frequentist
numerator:
type: number
denominator:
type: number
mean:
type: number
stddev:
type: number
percentChange:
type: number
effectStandardError:
description: >-
Standard error of the estimated effect
(`percentChange`).
type: number
ciLow:
type: number
ciHigh:
type: number
pValue:
type: number
risk:
type: number
chanceToBeatControl:
type: number
errorMessage:
type: string
required:
- engine
- numerator
- denominator
- mean
- stddev
- percentChange
- effectStandardError
- ciLow
- ciHigh
additionalProperties: false
required:
- variationId
- analyses
additionalProperties: false
required:
- metricId
- variations
additionalProperties: false
required:
- dimension
- totalUsers
- checks
- metrics
additionalProperties: false
required:
- id
- dateUpdated
- experimentId
- phase
- dateStart
- dateEnd
- dimension
- settings
- queryIds
- results
additionalProperties: false
ExperimentWithEnhancedStatus:
allOf:
- type: object
properties:
id:
type: string
trackingKey:
type: string
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
name:
type: string
type:
type: string
enum:
- standard
- multi-armed-bandit
- holdout
project:
type: string
hypothesis:
type: string
description:
type: string
maxLength: 10000
tags:
type: array
items:
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
archived:
type: boolean
status:
type: string
autoRefresh:
type: boolean
hashAttribute:
type: string
fallbackAttribute:
type: string
hashVersion:
anyOf:
- type: number
const: 1
- type: number
const: 2
disableStickyBucketing:
type: boolean
bucketVersion:
type: number
minBucketVersion:
type: number
variations:
type: array
items:
type: object
properties:
variationId:
type: string
key:
type: string
name:
type: string
description:
type: string
maxLength: 10000
screenshots:
type: array
items:
type: string
required:
- variationId
- key
- name
- description
- screenshots
additionalProperties: false
phases:
type: array
items:
type: object
properties:
name:
type: string
dateStarted:
type: string
dateEnded:
type: string
reasonForStopping:
type: string
seed:
type: string
coverage:
type: number
trafficSplit:
type: array
items:
type: object
properties:
variationId:
type: string
weight:
type: number
required:
- variationId
- weight
additionalProperties: false
namespace:
type: object
properties:
namespaceId:
type: string
enabled:
type: boolean
range:
minItems: 2
maxItems: 2
type: array
items:
type: number
ranges:
type: array
items:
type: array
prefixItems:
- type: number
- type: number
required:
- namespaceId
additionalProperties: false
targetingCondition:
type: string
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
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
required:
- name
- dateStarted
- dateEnded
- reasonForStopping
- seed
- coverage
- trafficSplit
- targetingCondition
additionalProperties: false
settings:
$ref: '#/components/schemas/ExperimentAnalysisSettings'
resultSummary:
type: object
properties:
status:
type: string
winner:
type: string
conclusions:
type: string
releasedVariationId:
type: string
excludeFromPayload:
type: boolean
required:
- status
- winner
- conclusions
- releasedVariationId
- excludeFromPayload
additionalProperties: false
shareLevel:
type: string
enum:
- public
- organization
publicUrl:
type: string
banditScheduleValue:
type: number
banditScheduleUnit:
type: string
enum:
- days
- hours
banditBurnInValue:
type: number
banditBurnInUnit:
type: string
enum:
- days
- hours
banditConversionWindowValue:
type: number
banditConversionWindowUnit:
type: string
enum:
- days
- hours
linkedFeatures:
type: array
items:
type: string
attributeScopeAllProjects:
type: boolean
hasVisualChangesets:
type: boolean
hasURLRedirects:
type: boolean
customFields:
type: object
propertyNames:
type: string
additionalProperties: {}
customMetricSlices:
description: >-
Custom slices that apply to ALL applicable metrics in the
experiment
type: array
items:
type: object
properties:
slices:
type: array
items:
type: object
properties:
column:
type: string
levels:
type: array
items:
type: string
required:
- column
- levels
additionalProperties: false
required:
- slices
additionalProperties: false
precomputedUnitDimensionIds:
maxItems: 3
type: array
items:
type: string
defaultDashboardId:
description: ID of the default dashboard for this experiment.
type: string
templateId:
type: string
statusUpdateSchedule:
anyOf:
- description: >-
Scheduled start/end for an experiment. All fields optional;
the end may be an absolute `stopAt` or a deferred relative
`stopAfter`, but not both.
type: object
properties:
startAt:
description: >-
ISO datetime when the experiment should start. Must be
in the future. Setting or clearing this field
invalidates any existing staged start
(`nextScheduledStatusUpdate`); call POST
/experiments/{id}/start to stage the new schedule.
format: date-time
type: string
stopAt:
description: >-
ISO datetime when the experiment should stop. Resolved
from `stopAfter` at start when a relative end was set.
format: date-time
type: string
stopAfter:
description: >-
Relative end offset. Deferred: resolved to a concrete
`stopAt` at the experiment's actual start (or off
`dateStarted` when already running).
type: object
properties:
value:
type: integer
exclusiveMinimum: 0
unit:
type: string
enum:
- hours
- days
required:
- value
- unit
additionalProperties: false
scheduledStopPlan:
description: >-
End-of-experiment automation applied at the scheduled
end. Required whenever a `stopAt` or `stopAfter` is set
(any mode, including `notify`).
$ref: '#/components/schemas/ScheduledStopPlan'
additionalProperties: false
- type: 'null'
nextScheduledStatusUpdate:
anyOf:
- type: object
properties:
type:
type: string
enum:
- start
- stop
date:
format: date-time
type: string
required:
- type
- date
additionalProperties: false
- type: 'null'
required:
- id
- trackingKey
- dateCreated
- dateUpdated
- name
- type
- project
- hypothesis
- description
- tags
- owner
- archived
- status
- autoRefresh
- hashAttribute
- hashVersion
- variations
- phases
- settings
additionalProperties: false
- type: object
properties:
enhancedStatus:
type: object
properties:
status:
type: string
enum:
- Running
- Stopped
- Draft
- Scheduled
- Archived
detailedStatus:
type: string
required:
- status
additionalProperties: false
additionalProperties: false
VisualChangeset:
type: object
properties:
id:
type: string
urlPatterns:
type: array
items:
type: object
properties:
include:
type: boolean
type:
type: string
enum:
- simple
- regex
pattern:
type: string
required:
- type
- pattern
additionalProperties: false
editorUrl:
type: string
experiment:
type: string
contextualBandit:
type: string
visualChanges:
type: array
items:
type: object
properties:
id:
type: string
description:
type: string
css:
type: string
js:
type: string
variation:
type: string
domMutations:
type: array
items:
type: object
properties:
selector:
type: string
action:
type: string
enum:
- append
- set
- remove
attribute:
type: string
value:
type: string
parentSelector:
type: string
insertBeforeSelector:
type: string
required:
- selector
- action
- attribute
additionalProperties: false
required:
- variation
- domMutations
additionalProperties: false
required:
- urlPatterns
- editorUrl
- visualChanges
additionalProperties: false
Metric:
type: object
properties:
id:
type: string
managedBy:
description: >-
Where this metric must be managed from. If not set (empty string),
it can be managed from anywhere.
type: string
enum:
- ''
- api
- config
- admin
dateCreated:
type: string
dateUpdated:
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
datasourceId:
type: string
name:
type: string
description:
type: string
maxLength: 10000
type:
type: string
enum:
- binomial
- count
- duration
- revenue
tags:
type: array
items:
type: string
projects:
type: array
items:
type: string
archived:
type: boolean
behavior:
type: object
properties:
goal:
type: string
enum:
- increase
- decrease
cappingSettings:
description: Controls how outliers are handled
type: object
properties:
type:
type: string
enum:
- none
- absolute
- percentile
value:
description: >-
When type is absolute, this is the absolute value. When type
is percentile, this is the percentile value (from 0.0 to
1.0).
type: number
ignoreZeros:
description: >-
If true and capping is `percentile`, zeros will be ignored
when calculating the percentile.
type: boolean
required:
- type
additionalProperties: false
cap:
deprecated: true
type: number
capping:
deprecated: true
anyOf:
- type: string
enum:
- absolute
- percentile
- type: 'null'
capValue:
deprecated: true
type: number
windowSettings:
description: Controls the conversion window for the metric
type: object
properties:
type:
type: string
enum:
- none
- conversion
- lookback
delayValue:
description: >-
Wait this long after experiment exposure before counting
conversions
type: number
delayUnit:
type: string
enum:
- minutes
- hours
- days
- weeks
windowValue:
type: number
windowUnit:
type: string
enum:
- minutes
- hours
- days
- weeks
required:
- type
additionalProperties: false
priorSettings:
description: Controls the bayesian prior for the metric.
type: object
properties:
override:
description: >-
If false, the organization default settings will be used
instead of the other settings in this object
type: boolean
proper:
description: >-
If true, the `mean` and `stddev` will be used, otherwise we
will use an improper flat prior.
type: boolean
mean:
description: >-
The mean of the prior distribution of relative effects in
proportion terms (e.g. 0.01 is 1%)
type: number
stddev:
description: >-
Must be > 0. The standard deviation of the prior
distribution of relative effects in proportion terms.
type: number
exclusiveMinimum: 0
required:
- override
- proper
- mean
- stddev
additionalProperties: false
conversionWindowStart:
deprecated: true
type: number
conversionWindowEnd:
deprecated: true
type: number
riskThresholdSuccess:
description: No longer used. Always the default value.
deprecated: true
type: number
riskThresholdDanger:
description: No longer used. Always the default value.
deprecated: true
type: number
minPercentChange:
type: number
maxPercentChange:
type: number
minSampleSize:
type: number
targetMDE:
type: number
required:
- goal
- windowSettings
- riskThresholdSuccess
- riskThresholdDanger
- minPercentChange
- maxPercentChange
- minSampleSize
- targetMDE
additionalProperties: false
sql:
type: object
properties:
identifierTypes:
type: array
items:
type: string
conversionSQL:
type: string
userAggregationSQL:
type: string
denominatorMetricId:
type: string
required:
- identifierTypes
- conversionSQL
- userAggregationSQL
- denominatorMetricId
additionalProperties: false
sqlBuilder:
type: object
properties:
identifierTypeColumns:
type: array
items:
type: object
properties:
identifierType:
type: string
columnName:
type: string
required:
- identifierType
- columnName
additionalProperties: false
tableName:
type: string
valueColumnName:
type: string
timestampColumnName:
type: string
conditions:
type: array
items:
type: object
properties:
column:
type: string
operator:
type: string
value:
type: string
required:
- column
- operator
- value
additionalProperties: false
required:
- identifierTypeColumns
- tableName
- valueColumnName
- timestampColumnName
- conditions
additionalProperties: false
mixpanel:
type: object
properties:
eventName:
type: string
eventValue:
type: string
userAggregation:
type: string
conditions:
type: array
items:
type: object
properties:
property:
type: string
operator:
type: string
value:
type: string
required:
- property
- operator
- value
additionalProperties: false
required:
- eventName
- eventValue
- userAggregation
- conditions
additionalProperties: false
required:
- id
- managedBy
- dateCreated
- dateUpdated
- owner
- datasourceId
- name
- description
- type
- tags
- projects
- archived
- behavior
additionalProperties: false
MetricUsage:
type: object
properties:
metricId:
description: The metric ID
type: string
error:
description: >-
Set when the metric does not exist or the caller has no permission
to read it.
type: string
experiments:
description: List of experiments using this metric
type: array
items:
type: object
properties:
experimentId:
description: The experiment ID
type: string
experimentStatus:
description: The current status of the experiment
type: string
enum:
- draft
- running
- stopped
lastSnapshotAttempt:
description: The last time a snapshot was attempted for this experiment
anyOf:
- format: date-time
type: string
- type: 'null'
required:
- experimentId
- experimentStatus
- lastSnapshotAttempt
additionalProperties: false
lastSnapshotAttempt:
description: >-
The most recent snapshot attempt across all experiments using this
metric
anyOf:
- format: date-time
type: string
- type: 'null'
required:
- metricId
additionalProperties: false
Segment:
type: object
properties:
id:
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
datasourceId:
type: string
identifierType:
type: string
name:
type: string
description:
type: string
maxLength: 10000
query:
type: string
dateCreated:
type: string
dateUpdated:
type: string
managedBy:
description: >-
Where this segment must be managed from. If not set (empty string),
it can be managed from anywhere.
type: string
enum:
- ''
- api
- config
type:
type: string
enum:
- SQL
- FACT
factTableId:
type: string
filters:
type: array
items:
type: string
projects:
type: array
items:
type: string
required:
- id
- owner
- datasourceId
- identifierType
- name
- dateCreated
- dateUpdated
additionalProperties: false
Dimension:
type: object
properties:
id:
type: string
dateCreated:
type: string
dateUpdated:
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
datasourceId:
type: string
identifierType:
type: string
name:
type: string
description:
type: string
maxLength: 10000
query:
type: string
managedBy:
description: >-
Where this dimension must be managed from. If not set (empty
string), it can be managed from anywhere.
type: string
enum:
- ''
- api
- config
required:
- id
- dateCreated
- dateUpdated
- owner
- datasourceId
- identifierType
- name
- query
additionalProperties: false
Project:
type: object
properties:
id:
type: string
name:
type: string
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
description:
type: string
maxLength: 10000
publicId:
description: >-
URL-safe slug used in SDK payload metadata. Auto-generated from name
if not provided.
type: string
restrictAccess:
description: >-
When true, only members with an explicit role on this Project
(directly or via a team) can access it. Members with the manageTeam
permission retain access.
type: boolean
allowTargeting:
description: >-
Whether Feature Flags owned by other Projects may add this Project
to their Targeting Projects. Defaults to true. Turning it off blocks
new targeting (and All Projects); existing targeting is kept.
type: boolean
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
settings:
type: object
properties:
statsEngine:
type: string
confidenceLevel:
type: number
pValueThreshold:
type: number
additionalProperties: false
required:
- id
- name
- dateCreated
- dateUpdated
- owner
additionalProperties: false
Environment:
type: object
properties:
id:
type: string
description:
type: string
toggleOnList:
type: boolean
defaultState:
type: boolean
projects:
type: array
items:
type: string
parent:
type: string
required:
- id
- description
- toggleOnList
- defaultState
- projects
additionalProperties: false
Attribute:
type: object
properties:
property:
type: string
datatype:
type: string
enum:
- boolean
- string
- number
- secureString
- enum
- string[]
- number[]
- secureString[]
description:
type: string
hashAttribute:
type: boolean
archived:
type: boolean
enum:
description: >-
Comma-separated list of allowed values. Required for the 'enum'
datatype. For array datatypes (string[], number[], secureString[])
it optionally restricts the list to these values. Ignored for all
other datatypes.
type: string
format:
type: string
enum:
- ''
- version
- date
- isoCountryCode
projects:
type: array
items:
type: string
tags:
type: array
items:
type: string
customFields:
type: object
propertyNames:
type: string
additionalProperties:
type: string
required:
- property
- datatype
additionalProperties: false
SdkConnection:
type: object
properties:
id:
type: string
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
name:
type: string
organization:
type: string
languages:
type: array
items:
type: string
sdkVersion:
type: string
environment:
type: string
project:
description: >-
Use 'projects' instead. This is only for backwards compatibility and
contains the first project only.
type: string
projects:
type: array
items:
type: string
encryptPayload:
type: boolean
encryptionKey:
type: string
includeVisualExperiments:
type: boolean
includeDraftExperiments:
type: boolean
includeDraftExperimentRefs:
description: >-
When true, experiment-ref rules linked to draft experiments are
included in feature definitions. Off by default.
type: boolean
includeExperimentNames:
type: boolean
includeRedirectExperiments:
type: boolean
includeRuleIds:
type: boolean
includeProjectIdInMetadata:
type: boolean
includeCustomFieldsInMetadata:
type: boolean
allowedCustomFieldsInMetadata:
type: array
items:
type: string
includeTagsInMetadata:
type: boolean
includeExperimentScheduleInMetadata:
type: boolean
key:
type: string
proxyEnabled:
type: boolean
proxyHost:
type: string
proxySigningKey:
type: string
sseEnabled:
type: boolean
hashSecureAttributes:
type: boolean
remoteEvalEnabled:
type: boolean
savedGroupReferencesEnabled:
description: Deprecated. Use `savedGroupFormat`.
type: boolean
savedGroupFormat:
description: >-
How Saved Groups are written into this connection's payload.
`referencesV2` needs an SDK version that supports it; the payload
steps down to `referencesV1` if not.
type: string
enum:
- inline
- referencesV1
- referencesV2
includeReferencedPrerequisites:
type: boolean
required:
- id
- dateCreated
- dateUpdated
- name
- organization
- languages
- environment
- project
- encryptPayload
- encryptionKey
- key
- proxyEnabled
- proxyHost
- proxySigningKey
additionalProperties: false
DataSource:
type: object
properties:
id:
type: string
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
type:
type: string
name:
type: string
description:
type: string
maxLength: 10000
projectIds:
type: array
items:
type: string
eventTracker:
type: string
identifierTypes:
type: array
items:
type: object
properties:
id:
type: string
description:
type: string
maxLength: 10000
required:
- id
- description
additionalProperties: false
assignmentQueries:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
maxLength: 10000
identifierTypes:
type: array
items:
type: string
identifierType:
deprecated: true
type: string
sql:
type: string
includesNameColumns:
type: boolean
dimensionColumns:
type: array
items:
type: string
projects:
type: array
items:
type: string
columnMapping:
description: >-
The column `sql` returns for each role, where it isn't the
canonical name (`experiment_id`, `variation_id`, `timestamp`,
`experiment_name`, `variation_name`, or the identifier type's
own name). Roles not listed use the canonical name.
type: object
properties:
experimentIdColumn:
type: string
variationIdColumn:
type: string
timestampColumn:
type: string
userIdColumns:
description: Column for each identifier type, keyed by type
type: object
propertyNames:
type: string
additionalProperties:
type: string
experimentNameColumn:
type: string
variationNameColumn:
type: string
additionalProperties: false
required:
- id
- name
- description
- identifierTypes
- identifierType
- sql
- includesNameColumns
- dimensionColumns
- projects
additionalProperties: false
identifierJoinQueries:
type: array
items:
type: object
properties:
identifierTypes:
type: array
items:
type: string
sql:
type: string
required:
- identifierTypes
- sql
additionalProperties: false
mixpanelSettings:
type: object
properties:
viewedExperimentEventName:
type: string
experimentIdProperty:
type: string
variationIdProperty:
type: string
extraUserIdProperty:
type: string
required:
- viewedExperimentEventName
- experimentIdProperty
- variationIdProperty
- extraUserIdProperty
additionalProperties: false
required:
- id
- dateCreated
- dateUpdated
- type
- name
- description
- projectIds
- eventTracker
- identifierTypes
- assignmentQueries
- identifierJoinQueries
additionalProperties: false
InformationSchema:
type: object
properties:
id:
type: string
datasourceId:
type: string
status:
type: string
enum:
- PENDING
- COMPLETE
error:
type: object
properties:
errorType:
type: string
enum:
- generic
- not_supported
- missing_params
message:
type: string
required:
- errorType
- message
additionalProperties: false
databases:
type: array
items:
type: object
properties:
databaseName:
type: string
path:
type: string
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
schemas:
type: array
items:
type: object
properties:
schemaName:
type: string
path:
type: string
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
tables:
type: array
items:
type: object
properties:
tableName:
type: string
path:
type: string
id:
type: string
numOfColumns:
type: number
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
required:
- tableName
- id
- numOfColumns
- dateCreated
- dateUpdated
additionalProperties: false
required:
- schemaName
- dateCreated
- dateUpdated
- tables
additionalProperties: false
required:
- databaseName
- dateCreated
- dateUpdated
- schemas
additionalProperties: false
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
required:
- id
- datasourceId
- status
- databases
- dateCreated
- dateUpdated
additionalProperties: false
VisualEditorCbExperimentStub:
type: object
properties:
id:
type: string
trackingKey:
type: string
name:
type: string
status:
type: string
project:
type: string
hashAttribute:
type: string
hashVersion:
type: number
const: 2
type:
type: string
const: contextual-bandit
variations:
type: array
items:
type: object
properties:
variationId:
type: string
key:
type: string
name:
type: string
description:
type: string
status:
type: string
enum:
- active
- pending
- deactivated
required:
- variationId
- key
- name
- description
additionalProperties: false
required:
- id
- trackingKey
- name
- status
- project
- hashAttribute
- hashVersion
- type
- variations
additionalProperties: false
SavedGroup:
type: object
properties:
id:
type: string
type:
type: string
enum:
- condition
- list
- remote
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
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
condition:
description: >-
When type = 'condition', this is the JSON-encoded condition for the
group
type: string
attributeKey:
description: >-
When type = 'list' or 'remote', this is the attribute key the group
is based on
type: string
values:
description: When type = 'list', this is the list of values for the attribute key
type: array
items:
type: string
description:
type: string
maxLength: 10000
projects:
type: array
items:
type: string
archived:
type: boolean
useEmptyListGroup:
type: boolean
currentUploadVersion:
description: >-
When type = 'remote', the version of the upload the group uses.
Absent when it uses none.
type: integer
currentUpload:
description: >-
When type = 'remote', the upload whose IDs the group uses, or null
if it has none. Loaders load this version.
anyOf:
- type: object
properties:
version:
type: integer
dateCreated:
format: date-time
type: string
numeric:
description: >-
Whether the group's attribute is a number. Loaders store
number IDs in their shortest form, String(Number(id)).
type: boolean
required:
- version
- dateCreated
- numeric
additionalProperties: false
- type: 'null'
required:
- id
- type
- dateCreated
- dateUpdated
- name
additionalProperties: false
SavedGroupRevision:
type: object
properties:
id:
type: string
version:
type: integer
title:
type: string
status:
type: string
enum:
- draft
- pending-review
- approved
- changes-requested
- merged
- discarded
authorId:
description: >-
Who acted: a member's user ID, or an API key's ID when it acted as
itself
type: string
author:
description: Who created the revision, with an API key's name
$ref: '#/components/schemas/EventUser'
authorEmail:
type: string
contributors:
type: array
items:
type: string
revertedFrom:
type: string
reviews:
type: array
items:
$ref: '#/components/schemas/SavedGroupRevisionReview'
activityLog:
type: array
items:
$ref: '#/components/schemas/SavedGroupRevisionActivityLogEntry'
autoPublishOnApproval:
description: Publish automatically the moment this revision is approved.
type: boolean
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:
description: Who armed the deferred publish, with an API key's name
$ref: '#/components/schemas/EventUser'
scheduledPublishAt:
description: >-
When the deferred publish fires. Absent when the revision publishes
on approval instead, or is not armed at all.
format: date-time
type: string
scheduledPublishLockEdits:
description: Content edits to this revision are frozen until it fires.
type: boolean
scheduledPublishLockOthers:
description: >-
Other revisions of the same resource cannot publish until this one
fires or is cancelled.
type: boolean
scheduledPublishBypassApproval:
description: >-
Armed by a caller who bypassed the approval requirement. Such a
schedule must be cancelled and re-armed rather than edited.
type: boolean
scheduledPublishAttempts:
description: How many times the poller has tried to publish this revision.
type: integer
scheduledPublishLastError:
description: Why the most recent deferred-publish attempt failed.
type: string
scheduledPublishGaveUpAt:
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.
format: date-time
type: string
resolution:
type: object
properties:
action:
type: string
enum:
- merged
- discarded
userId:
description: >-
Who acted: a member's user ID, or an API key's ID when it acted
as itself
type: string
user:
$ref: '#/components/schemas/EventUser'
dateCreated:
format: date-time
type: string
required:
- action
- userId
- dateCreated
additionalProperties: false
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
baseSavedGroup:
$ref: '#/components/schemas/SavedGroup'
proposedSavedGroup:
$ref: '#/components/schemas/SavedGroup'
proposedChanges:
type: array
items:
anyOf:
- type: object
properties:
op:
type: string
const: add
path:
type: string
pattern: ^\/[^/]+$
value: {}
required:
- op
- path
- value
additionalProperties: false
- type: object
properties:
op:
type: string
const: remove
path:
type: string
pattern: ^\/[^/]+$
required:
- op
- path
additionalProperties: false
- type: object
properties:
op:
type: string
const: replace
path:
type: string
pattern: ^\/[^/]+$
value: {}
required:
- op
- path
- value
additionalProperties: false
- type: object
properties:
op:
type: string
const: move
from:
type: string
pattern: ^\/[^/]+$
path:
type: string
pattern: ^\/[^/]+$
required:
- op
- from
- path
additionalProperties: false
- type: object
properties:
op:
type: string
const: copy
from:
type: string
pattern: ^\/[^/]+$
path:
type: string
pattern: ^\/[^/]+$
required:
- op
- from
- path
additionalProperties: false
- type: object
properties:
op:
type: string
const: test
path:
type: string
pattern: ^\/[^/]+$
value: {}
required:
- op
- path
- value
additionalProperties: false
required:
- id
- status
- authorId
- reviews
- activityLog
- dateCreated
- dateUpdated
- baseSavedGroup
- proposedSavedGroup
- proposedChanges
additionalProperties: false
SavedGroupRevisionReview:
type: object
properties:
id:
type: string
userId:
description: >-
Who acted: a member's user ID, or an API key's ID when it acted as
itself
type: string
decision:
type: string
enum:
- approve
- request-changes
- comment
comment:
type: string
stale:
description: >-
True if a later review cycle (re-submit, approval reset, recall, or
reopen) superseded this verdict. Stale verdicts are kept for
attribution but no longer count as an active approval or
change-request.
type: boolean
dateCreated:
format: date-time
type: string
user:
$ref: '#/components/schemas/EventUser'
required:
- id
- userId
- decision
- dateCreated
additionalProperties: false
SavedGroupRevisionActivityLogEntry:
type: object
properties:
id:
type: string
userId:
description: >-
Who acted: a member's user ID, or an API key's ID when it acted as
itself
type: string
action:
type: string
enum:
- created
- updated
- reviewed
- approved
- requested-changes
- commented
- review-requested
- review-retracted
- merged
- discarded
- reopened
- recalled
- scheduled-publish
- scheduled-publish-updated
- scheduled-publish-canceled
- merge-recovered
description:
anyOf:
- type: string
- type: 'null'
proposedChangesSnapshot:
type: array
items:
anyOf:
- type: object
properties:
op:
type: string
const: add
path:
type: string
pattern: ^\/[^/]+$
value: {}
required:
- op
- path
- value
additionalProperties: false
- type: object
properties:
op:
type: string
const: remove
path:
type: string
pattern: ^\/[^/]+$
required:
- op
- path
additionalProperties: false
- type: object
properties:
op:
type: string
const: replace
path:
type: string
pattern: ^\/[^/]+$
value: {}
required:
- op
- path
- value
additionalProperties: false
- type: object
properties:
op:
type: string
const: move
from:
type: string
pattern: ^\/[^/]+$
path:
type: string
pattern: ^\/[^/]+$
required:
- op
- from
- path
additionalProperties: false
- type: object
properties:
op:
type: string
const: copy
from:
type: string
pattern: ^\/[^/]+$
path:
type: string
pattern: ^\/[^/]+$
required:
- op
- from
- path
additionalProperties: false
- type: object
properties:
op:
type: string
const: test
path:
type: string
pattern: ^\/[^/]+$
value: {}
required:
- op
- path
- value
additionalProperties: false
targetSnapshot: {}
dateCreated:
format: date-time
type: string
user:
$ref: '#/components/schemas/EventUser'
required:
- id
- userId
- action
- dateCreated
additionalProperties: false
SavedGroupReferenceResource:
type: object
properties:
id:
type: string
name:
type: string
project:
type: string
required:
- id
additionalProperties: false
SavedGroupUpload:
type: object
properties:
savedGroupId:
type: string
version:
type: integer
fileName:
description: The uploaded file's original name, if it was given
anyOf:
- type: string
- type: 'null'
size:
description: File size in bytes
type: integer
sha256:
description: >-
Hex SHA-256 of the file, set once it's validated. Null if it isn't
validated yet, or wasn't read in full.
anyOf:
- type: string
- type: 'null'
dateCreated:
format: date-time
type: string
createdBy:
description: >-
Who uploaded it: a user ID, or an API key ID (`key_…`) for a key
acting as itself
type: string
status:
description: >-
`pending` until GrowthBook has checked the whole file. Loaders only
see `valid` uploads.
anyOf:
- type: object
properties:
type:
type: string
const: pending
required:
- type
additionalProperties: false
- type: object
properties:
type:
type: string
const: valid
idCount:
description: IDs in the file, before removing duplicates
type: integer
minimum: 0
required:
- type
- idCount
additionalProperties: false
- type: object
properties:
type:
type: string
const: invalid
invalidLineCount:
type: integer
minimum: 0
errors:
description: The first problems found in the file
maxItems: 10
type: array
items:
type: string
maxLength: 500
required:
- type
- invalidLineCount
- errors
additionalProperties: false
loads:
description: Each data store's latest report on loading this upload
type: array
items:
type: object
properties:
storeId:
description: >-
The data store's ID, such as `redis-us-east`, set in the
loader's config. Loaders sharing a store (such as one Redis)
use the same ID. Shown in the UI.
type: string
minLength: 1
maxLength: 100
status:
description: >-
Loaders validate the file while loading it, so each store
reports its own result.
anyOf:
- type: object
properties:
type:
type: string
const: loading
required:
- type
additionalProperties: false
- type: object
properties:
type:
type: string
const: loaded
rowCount:
description: Unique IDs loaded
type: integer
minimum: 0
required:
- type
- rowCount
additionalProperties: false
- description: >-
The file has problems, so the store kept serving the
previous upload
type: object
properties:
type:
type: string
const: invalid
invalidLineCount:
type: integer
minimum: 0
errors:
description: The first problems found in the file
maxItems: 10
type: array
items:
type: string
maxLength: 500
required:
- type
- invalidLineCount
- errors
additionalProperties: false
- type: object
properties:
type:
type: string
const: failed
error:
description: A problem in the data store, not the file
type: string
maxLength: 2000
required:
- type
- error
additionalProperties: false
dateUpdated:
format: date-time
type: string
required:
- storeId
- status
- dateUpdated
additionalProperties: false
required:
- savedGroupId
- version
- fileName
- size
- sha256
- dateCreated
- createdBy
- status
- loads
additionalProperties: false
Constant:
type: object
properties:
id:
type: string
key:
description: Stable reference handle; used as `@const:key` in values
type: string
name:
type: string
type:
type: string
enum:
- string
- json
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
value:
description: >-
The default value (raw string for `string` constants, JSON-encoded
for `json` constants)
type: string
environmentValues:
description: >-
Per-environment value overrides (environment id → value). Falls back
to `value` when an environment is absent.
type: object
propertyNames:
type: string
additionalProperties:
type: string
description:
type: string
maxLength: 10000
project:
description: The project this constant belongs to (empty = all projects)
type: string
archived:
type: boolean
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
required:
- id
- key
- name
- type
- dateCreated
- dateUpdated
additionalProperties: false
ConstantRevision:
type: object
properties:
id:
type: string
version:
type: integer
title:
type: string
status:
type: string
enum:
- draft
- pending-review
- approved
- changes-requested
- merged
- discarded
authorId:
description: >-
Who acted: a member's user ID, or an API key's ID when it acted as
itself
type: string
author:
description: Who created the revision, with an API key's name
$ref: '#/components/schemas/EventUser'
authorEmail:
type: string
contributors:
type: array
items:
type: string
revertedFrom:
type: string
reviews:
type: array
items:
$ref: '#/components/schemas/ConstantRevisionReview'
activityLog:
type: array
items:
$ref: '#/components/schemas/ConstantRevisionActivityLogEntry'
autoPublishOnApproval:
description: Publish automatically the moment this revision is approved.
type: boolean
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:
description: Who armed the deferred publish, with an API key's name
$ref: '#/components/schemas/EventUser'
scheduledPublishAt:
description: >-
When the deferred publish fires. Absent when the revision publishes
on approval instead, or is not armed at all.
format: date-time
type: string
scheduledPublishLockEdits:
description: Content edits to this revision are frozen until it fires.
type: boolean
scheduledPublishLockOthers:
description: >-
Other revisions of the same resource cannot publish until this one
fires or is cancelled.
type: boolean
scheduledPublishBypassApproval:
description: >-
Armed by a caller who bypassed the approval requirement. Such a
schedule must be cancelled and re-armed rather than edited.
type: boolean
scheduledPublishAttempts:
description: How many times the poller has tried to publish this revision.
type: integer
scheduledPublishLastError:
description: Why the most recent deferred-publish attempt failed.
type: string
scheduledPublishGaveUpAt:
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.
format: date-time
type: string
resolution:
type: object
properties:
action:
type: string
enum:
- merged
- discarded
userId:
description: >-
Who acted: a member's user ID, or an API key's ID when it acted
as itself
type: string
user:
$ref: '#/components/schemas/EventUser'
dateCreated:
format: date-time
type: string
required:
- action
- userId
- dateCreated
additionalProperties: false
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
baseConstant:
$ref: '#/components/schemas/Constant'
proposedConstant:
$ref: '#/components/schemas/Constant'
proposedChanges:
type: array
items:
anyOf:
- type: object
properties:
op:
type: string
const: add
path:
type: string
pattern: ^\/[^/]+$
value: {}
required:
- op
- path
- value
additionalProperties: false
- type: object
properties:
op:
type: string
const: remove
path:
type: string
pattern: ^\/[^/]+$
required:
- op
- path
additionalProperties: false
- type: object
properties:
op:
type: string
const: replace
path:
type: string
pattern: ^\/[^/]+$
value: {}
required:
- op
- path
- value
additionalProperties: false
- type: object
properties:
op:
type: string
const: move
from:
type: string
pattern: ^\/[^/]+$
path:
type: string
pattern: ^\/[^/]+$
required:
- op
- from
- path
additionalProperties: false
- type: object
properties:
op:
type: string
const: copy
from:
type: string
pattern: ^\/[^/]+$
path:
type: string
pattern: ^\/[^/]+$
required:
- op
- from
- path
additionalProperties: false
- type: object
properties:
op:
type: string
const: test
path:
type: string
pattern: ^\/[^/]+$
value: {}
required:
- op
- path
- value
additionalProperties: false
required:
- id
- status
- authorId
- reviews
- activityLog
- dateCreated
- dateUpdated
- baseConstant
- proposedConstant
- proposedChanges
additionalProperties: false
ConstantRevisionReview:
type: object
properties:
id:
type: string
userId:
description: >-
Who acted: a member's user ID, or an API key's ID when it acted as
itself
type: string
decision:
type: string
enum:
- approve
- request-changes
- comment
comment:
type: string
stale:
description: >-
True if a later review cycle (re-submit, approval reset, recall, or
reopen) superseded this verdict. Stale verdicts are kept for
attribution but no longer count as an active approval or
change-request.
type: boolean
dateCreated:
format: date-time
type: string
user:
$ref: '#/components/schemas/EventUser'
required:
- id
- userId
- decision
- dateCreated
additionalProperties: false
ConstantRevisionActivityLogEntry:
type: object
properties:
id:
type: string
userId:
description: >-
Who acted: a member's user ID, or an API key's ID when it acted as
itself
type: string
action:
type: string
enum:
- created
- updated
- reviewed
- approved
- requested-changes
- commented
- review-requested
- review-retracted
- merged
- discarded
- reopened
- recalled
- scheduled-publish
- scheduled-publish-updated
- scheduled-publish-canceled
- merge-recovered
description:
anyOf:
- type: string
- type: 'null'
proposedChangesSnapshot:
type: array
items:
anyOf:
- type: object
properties:
op:
type: string
const: add
path:
type: string
pattern: ^\/[^/]+$
value: {}
required:
- op
- path
- value
additionalProperties: false
- type: object
properties:
op:
type: string
const: remove
path:
type: string
pattern: ^\/[^/]+$
required:
- op
- path
additionalProperties: false
- type: object
properties:
op:
type: string
const: replace
path:
type: string
pattern: ^\/[^/]+$
value: {}
required:
- op
- path
- value
additionalProperties: false
- type: object
properties:
op:
type: string
const: move
from:
type: string
pattern: ^\/[^/]+$
path:
type: string
pattern: ^\/[^/]+$
required:
- op
- from
- path
additionalProperties: false
- type: object
properties:
op:
type: string
const: copy
from:
type: string
pattern: ^\/[^/]+$
path:
type: string
pattern: ^\/[^/]+$
required:
- op
- from
- path
additionalProperties: false
- type: object
properties:
op:
type: string
const: test
path:
type: string
pattern: ^\/[^/]+$
value: {}
required:
- op
- path
- value
additionalProperties: false
targetSnapshot: {}
dateCreated:
format: date-time
type: string
user:
$ref: '#/components/schemas/EventUser'
required:
- id
- userId
- action
- dateCreated
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: >-
Who locked the config: a member's user ID, or an API key's ID when
it acted as itself
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
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
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
ConfigRevision:
type: object
properties:
id:
type: string
version:
type: integer
title:
type: string
status:
type: string
enum:
- draft
- pending-review
- approved
- changes-requested
- merged
- discarded
authorId:
description: >-
Who acted: a member's user ID, or an API key's ID when it acted as
itself
type: string
author:
description: Who created the revision, with an API key's name
$ref: '#/components/schemas/EventUser'
authorEmail:
type: string
contributors:
type: array
items:
type: string
revertedFrom:
type: string
reviews:
type: array
items:
$ref: '#/components/schemas/ConfigRevisionReview'
activityLog:
type: array
items:
$ref: '#/components/schemas/ConfigRevisionActivityLogEntry'
autoPublishOnApproval:
description: Publish automatically the moment this revision is approved.
type: boolean
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:
description: Who armed the deferred publish, with an API key's name
$ref: '#/components/schemas/EventUser'
scheduledPublishAt:
description: >-
When the deferred publish fires. Absent when the revision publishes
on approval instead, or is not armed at all.
format: date-time
type: string
scheduledPublishLockEdits:
description: Content edits to this revision are frozen until it fires.
type: boolean
scheduledPublishLockOthers:
description: >-
Other revisions of the same resource cannot publish until this one
fires or is cancelled.
type: boolean
scheduledPublishBypassApproval:
description: >-
Armed by a caller who bypassed the approval requirement. Such a
schedule must be cancelled and re-armed rather than edited.
type: boolean
scheduledPublishAttempts:
description: How many times the poller has tried to publish this revision.
type: integer
scheduledPublishLastError:
description: Why the most recent deferred-publish attempt failed.
type: string
scheduledPublishGaveUpAt:
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.
format: date-time
type: string
resolution:
type: object
properties:
action:
type: string
enum:
- merged
- discarded
userId:
description: >-
Who acted: a member's user ID, or an API key's ID when it acted
as itself
type: string
user:
$ref: '#/components/schemas/EventUser'
dateCreated:
format: date-time
type: string
required:
- action
- userId
- dateCreated
additionalProperties: false
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
baseConfig:
$ref: '#/components/schemas/Config'
proposedConfig:
$ref: '#/components/schemas/Config'
proposedChanges:
type: array
items:
anyOf:
- type: object
properties:
op:
type: string
const: add
path:
type: string
pattern: ^\/[^/]+$
value: {}
required:
- op
- path
- value
additionalProperties: false
- type: object
properties:
op:
type: string
const: remove
path:
type: string
pattern: ^\/[^/]+$
required:
- op
- path
additionalProperties: false
- type: object
properties:
op:
type: string
const: replace
path:
type: string
pattern: ^\/[^/]+$
value: {}
required:
- op
- path
- value
additionalProperties: false
- type: object
properties:
op:
type: string
const: move
from:
type: string
pattern: ^\/[^/]+$
path:
type: string
pattern: ^\/[^/]+$
required:
- op
- from
- path
additionalProperties: false
- type: object
properties:
op:
type: string
const: copy
from:
type: string
pattern: ^\/[^/]+$
path:
type: string
pattern: ^\/[^/]+$
required:
- op
- from
- path
additionalProperties: false
- type: object
properties:
op:
type: string
const: test
path:
type: string
pattern: ^\/[^/]+$
value: {}
required:
- op
- path
- value
additionalProperties: false
required:
- id
- status
- authorId
- reviews
- activityLog
- dateCreated
- dateUpdated
- baseConfig
- proposedConfig
- proposedChanges
additionalProperties: false
ConfigRevisionReview:
type: object
properties:
id:
type: string
userId:
description: >-
Who acted: a member's user ID, or an API key's ID when it acted as
itself
type: string
decision:
type: string
enum:
- approve
- request-changes
- comment
comment:
type: string
stale:
description: >-
True if a later review cycle (re-submit, approval reset, recall, or
reopen) superseded this verdict. Stale verdicts are kept for
attribution but no longer count as an active approval or
change-request.
type: boolean
dateCreated:
format: date-time
type: string
user:
$ref: '#/components/schemas/EventUser'
required:
- id
- userId
- decision
- dateCreated
additionalProperties: false
ConfigRevisionActivityLogEntry:
type: object
properties:
id:
type: string
userId:
description: >-
Who acted: a member's user ID, or an API key's ID when it acted as
itself
type: string
action:
type: string
enum:
- created
- updated
- reviewed
- approved
- requested-changes
- commented
- review-requested
- review-retracted
- merged
- discarded
- reopened
- recalled
- scheduled-publish
- scheduled-publish-updated
- scheduled-publish-canceled
- merge-recovered
description:
anyOf:
- type: string
- type: 'null'
proposedChangesSnapshot:
type: array
items:
anyOf:
- type: object
properties:
op:
type: string
const: add
path:
type: string
pattern: ^\/[^/]+$
value: {}
required:
- op
- path
- value
additionalProperties: false
- type: object
properties:
op:
type: string
const: remove
path:
type: string
pattern: ^\/[^/]+$
required:
- op
- path
additionalProperties: false
- type: object
properties:
op:
type: string
const: replace
path:
type: string
pattern: ^\/[^/]+$
value: {}
required:
- op
- path
- value
additionalProperties: false
- type: object
properties:
op:
type: string
const: move
from:
type: string
pattern: ^\/[^/]+$
path:
type: string
pattern: ^\/[^/]+$
required:
- op
- from
- path
additionalProperties: false
- type: object
properties:
op:
type: string
const: copy
from:
type: string
pattern: ^\/[^/]+$
path:
type: string
pattern: ^\/[^/]+$
required:
- op
- from
- path
additionalProperties: false
- type: object
properties:
op:
type: string
const: test
path:
type: string
pattern: ^\/[^/]+$
value: {}
required:
- op
- path
- value
additionalProperties: false
targetSnapshot: {}
dateCreated:
format: date-time
type: string
user:
$ref: '#/components/schemas/EventUser'
required:
- id
- userId
- action
- dateCreated
additionalProperties: false
FeatureRevisionRef:
type: object
properties:
entityType:
type: string
const: feature
id:
description: Feature Flag id.
type: string
version:
description: Revision version to publish.
type: integer
required:
- entityType
- id
- version
additionalProperties: false
SavedGroupRevisionRef:
type: object
properties:
entityType:
type: string
const: saved-group
id:
description: Saved Group id.
type: string
version:
description: Revision version to publish.
type: integer
required:
- entityType
- id
- version
additionalProperties: false
ConfigRevisionRef:
type: object
properties:
entityType:
type: string
const: config
key:
description: Config key.
type: string
version:
description: Revision version to publish.
type: integer
required:
- entityType
- key
- version
additionalProperties: false
ConstantRevisionRef:
type: object
properties:
entityType:
type: string
const: constant
key:
description: Constant key.
type: string
version:
description: Revision version to publish.
type: integer
required:
- entityType
- key
- version
additionalProperties: false
RevisionIdRef:
type: object
properties:
entityType:
type: string
enum:
- feature
- saved-group
- config
- constant
revisionId:
description: >-
A revision id from this API or the revision webhooks (`rev_…` /
`frev_…`). Alternative to identifier + version.
type: string
required:
- entityType
- revisionId
additionalProperties: false
CustomHook:
type: object
properties:
id:
type: string
name:
type: string
hook:
description: >-
Which save/publish event runs the hook (and which entity type it
validates)
type: string
enum:
- validateFeature
- validateFeatureRevision
- validateConfig
- validateConfigRevision
- validateExperiment
code:
description: >-
JavaScript function body executed in the sandbox. Throw an Error to
block the save; call `addWarning(msg)` for a soft warning.
type: string
enabled:
type: boolean
projects:
description: >-
Project ids the hook applies to (empty = all projects). Always empty
for entity-scoped hooks.
type: array
items:
type: string
entityType:
description: Set (with entityId) to scope the hook to a single resource.
type: string
enum:
- feature
- config
- experiment
entityId:
description: >-
The scoped resource: a feature id, or a config key. A config-scoped
hook always runs for that config and every config that inherits from
it (via parent/extends, transitively).
type: string
incrementalChangesOnly:
description: >-
When true, errors/warnings that already existed before the change
being validated are suppressed
type: boolean
lastSuccess:
format: date-time
type: string
lastFailure:
format: date-time
type: string
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
required:
- id
- name
- hook
- code
- enabled
- projects
- dateCreated
- dateUpdated
additionalProperties: false
Organization:
type: object
properties:
id:
description: The Growthbook unique identifier for the organization
type: string
externalId:
description: >-
An optional identifier that you use within your company for the
organization
type: string
dateCreated:
format: date-time
description: The date the organization was created
type: string
name:
description: The name of the organization
type: string
ownerEmail:
description: The email address of the organization owner
type: string
additionalProperties: false
FactTable:
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
maxLength: 10000
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
projects:
type: array
items:
type: string
tags:
type: array
items:
type: string
datasource:
type: string
userIdTypes:
type: array
items:
type: string
userIdColumns:
description: >-
Maps an identifier type to the column holding it, for SQL that does
not alias its columns to the identifier type names, e.g.
`{"user_id": "userId"}`. May also be a single-level field path into
a JSON column (`properties.userId`). Unmapped types use the
identifier type name as the column name.
type: object
propertyNames:
type: string
additionalProperties:
type: string
aggregatedFactTableSettings:
description: >-
Settings for maintaining shared daily aggregated tables (a subset of
userIdTypes plus the daily update time and restate lookback window)
used to speed up CUPED. Requires the data pipeline (pipeline-mode)
feature.
type: object
properties:
idTypes:
type: array
items:
type: string
updateTime:
type: object
properties:
time:
type: string
timezone:
type: string
required:
- time
- timezone
additionalProperties: false
lookbackWindow:
type: integer
exclusiveMinimum: 0
restateChunkDays:
type: integer
minimum: 1
maximum: 7
required:
- idTypes
- updateTime
- lookbackWindow
additionalProperties: false
sql:
type: string
timestampColumn:
description: >-
The column holding the event timestamp. Must be a date column on
this fact table. Defaults to "timestamp" when unset.
type: string
eventName:
description: The event name used in SQL template variables
type: string
columns:
description: Array of column definitions for this fact table
type: array
items:
$ref: '#/components/schemas/FactTableColumn'
columnsError:
readOnly: true
description: Error message if there was an issue parsing the SQL schema
anyOf:
- type: string
- type: 'null'
columnRefreshPending:
description: >-
True while the fact table's column schema is being detected in the
background. While true, `columns` may be empty or incomplete and
metrics referencing not-yet-detected columns cannot be created.
type: boolean
archived:
type: boolean
autoSliceUpdatesEnabled:
description: >-
Whether Auto Slice values for this fact table's columns are
refreshed automatically in the background.
type: boolean
managedBy:
description: >-
Where this fact table must be managed from. If not set (empty
string), it can be managed from anywhere.
type: string
enum:
- ''
- api
- admin
- dbt
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
required:
- id
- name
- description
- owner
- projects
- tags
- datasource
- userIdTypes
- sql
- managedBy
- dateCreated
- dateUpdated
additionalProperties: false
FactTableColumn:
type: object
properties:
column:
description: The actual column name in the database/SQL query
type: string
datatype:
description: >-
The column's data type (can be an override of the warehouse-reported
datatype, for JSON string columns for example).
type: string
enum:
- number
- string
- date
- boolean
- json
- binary
- other
- ''
dataTypeFromWarehouse:
readOnly: true
description: The warehouse-reported datatype.
type: string
enum:
- number
- string
- date
- boolean
- json
- binary
- other
- ''
numberFormat:
type: string
enum:
- ''
- currency
- time:seconds
- time:milliseconds
- memory:bytes
- memory:kilobytes
jsonFields:
description: For JSON columns, defines the structure of nested fields
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
datatype:
type: string
enum:
- number
- string
- date
- boolean
- json
- binary
- other
- ''
additionalProperties: false
name:
description: >-
Display name for the column (can be different from the actual column
name)
type: string
description:
description: What the column contains.
type: string
maxLength: 10000
alwaysInlineFilter:
default: false
description: >-
Whether this column should always be included as an inline filter in
queries
type: boolean
conditionalInlineFilters:
description: >-
Value -> additional column to prompt for when a metric filters this
column to that value, e.g. {"Page View": "path", "Modal Open":
"properties.modalType"}. Requires alwaysInlineFilter.
type: object
propertyNames:
type: string
additionalProperties:
type: string
deleted:
default: false
type: boolean
isAutoSliceColumn:
default: false
description: >-
Whether this column can be used for auto slice analysis. This is an
enterprise feature.
type: boolean
autoSlices:
description: Specific slices to automatically analyze for this column.
type: array
items:
type: string
lockedAutoSlices:
description: >-
Locked slices that are protected from automatic updates. These will
always be included in the slice levels even if they're not in the
top values query results.
type: array
items:
type: string
isVirtual:
default: false
description: >-
Whether this is a virtual (computed) column defined by a SQL
expression rather than detected from the fact table SQL. Can be set
when creating a column, but a column's origin cannot be changed
afterwards — sending a value that contradicts an existing column is
rejected.
type: boolean
sql:
description: >-
For virtual columns, the SQL expression that computes the column
value. Only valid on a virtual column; when omitted from an update,
the existing expression is preserved.
type: string
topValues:
readOnly: true
description: >-
The most common values for this column, sampled from the warehouse
to populate filter pickers and auto slices. Read-only.
type: array
items:
type: string
topValuesDate:
readOnly: true
format: date-time
description: When topValues was last refreshed for this column.
type: string
dateCreated:
readOnly: true
format: date-time
type: string
dateUpdated:
readOnly: true
format: date-time
type: string
required:
- column
- datatype
additionalProperties: false
FactTableColumnInput:
type: object
properties:
column:
description: The actual column name in the database/SQL query
type: string
datatype:
description: >-
The column's data type. Omit (or send "") to have it auto-detected
from the SQL.
type: string
enum:
- number
- string
- date
- boolean
- json
- binary
- other
- ''
numberFormat:
type: string
enum:
- ''
- currency
- time:seconds
- time:milliseconds
- memory:bytes
- memory:kilobytes
jsonFields:
description: For JSON columns, defines the structure of nested fields
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
datatype:
type: string
enum:
- number
- string
- date
- boolean
- json
- binary
- other
- ''
additionalProperties: false
name:
description: >-
Display name for the column (can be different from the actual column
name)
type: string
description:
description: What the column contains.
type: string
maxLength: 10000
alwaysInlineFilter:
default: false
description: >-
Whether this column should always be included as an inline filter in
queries
type: boolean
conditionalInlineFilters:
description: >-
Value -> additional column to prompt for when a metric filters this
column to that value, e.g. {"Page View": "path", "Modal Open":
"properties.modalType"}. Requires alwaysInlineFilter.
type: object
propertyNames:
type: string
additionalProperties:
type: string
deleted:
default: false
type: boolean
isAutoSliceColumn:
default: false
description: >-
Whether this column can be used for auto slice analysis. This is an
enterprise feature.
type: boolean
autoSlices:
description: Specific slices to automatically analyze for this column.
type: array
items:
type: string
lockedAutoSlices:
description: >-
Locked slices that are protected from automatic updates. These will
always be included in the slice levels even if they're not in the
top values query results.
type: array
items:
type: string
isVirtual:
default: false
description: >-
Whether this is a virtual (computed) column defined by a SQL
expression rather than detected from the fact table SQL. Can be set
when creating a column, but a column's origin cannot be changed
afterwards — sending a value that contradicts an existing column is
rejected.
type: boolean
sql:
description: >-
For virtual columns, the SQL expression that computes the column
value. Only valid on a virtual column; when omitted from an update,
the existing expression is preserved.
type: string
required:
- column
additionalProperties: false
FactTableFilter:
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
maxLength: 10000
value:
type: string
managedBy:
description: >-
Where this fact table filter must be managed from. If not set (empty
string), it can be managed from anywhere.
type: string
enum:
- ''
- api
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
required:
- id
- name
- description
- value
- managedBy
- dateCreated
- dateUpdated
additionalProperties: false
AggregatedFactTable:
type: object
properties:
idType:
description: The id type this aggregated table is keyed by
type: string
status:
description: >-
Materialization status: `pending` (not yet built), `running` (a
refresh is in progress), `active` (materialized and queryable), or
`error` (the last run failed).
type: string
enum:
- running
- error
- pending
- active
tableFullName:
description: >-
Fully-qualified warehouse table name, or null if it has not been
created yet
anyOf:
- type: string
- type: 'null'
firstEventDate:
description: Earliest event date covered by the materialized data
anyOf:
- format: date-time
type: string
- type: 'null'
lastEventDate:
description: Latest event date covered by the materialized data
anyOf:
- format: date-time
type: string
- type: 'null'
lastMaxTimestamp:
description: >-
Event-time high-water mark; the next incremental refresh appends
events after this timestamp
anyOf:
- format: date-time
type: string
- type: 'null'
lastError:
description: Error message from the last failed run, if any
anyOf:
- type: string
- type: 'null'
dateUpdated:
description: When the aggregation metadata was last updated
anyOf:
- format: date-time
type: string
- type: 'null'
pendingRestate:
description: >-
Whether the next run will be forced to drop and rebuild the table
instead of appending incrementally
type: boolean
pendingRestateReason:
description: Why a restate is pending, if `pendingRestate` is true
anyOf:
- type: string
enum:
- incomplete-write
- schema-drift
- type: 'null'
required:
- idType
- status
- tableFullName
- firstEventDate
- lastEventDate
- lastMaxTimestamp
- lastError
- dateUpdated
- pendingRestate
- pendingRestateReason
additionalProperties: false
AggregatedTableRefreshTrigger:
type: object
properties:
idType:
description: The id type this refresh targets
type: string
runId:
description: >-
The id of the run, set when status is started or failed and null
when skipped.
anyOf:
- type: string
- type: 'null'
status:
description: Whether a refresh was started, failed to be created, or was skipped
type: string
enum:
- started
- failed
- skipped
reason:
description: Why the refresh was skipped, when status is skipped.
anyOf:
- type: string
enum:
- already-in-progress
- datasource-not-found
- pipeline-not-configured
- unsupported-datasource
- no-eligible-metrics
- type: 'null'
error:
description: The error message when status is failed; null otherwise.
anyOf:
- type: string
- type: 'null'
required:
- idType
- runId
- status
- reason
- error
additionalProperties: false
AggregatedTableRunSummary:
type: object
properties:
id:
description: The run id (e.g. aftr_...)
type: string
idType:
description: The id type this run materialized
type: string
mode:
description: Whether this run appended new data or rebuilt the table
type: string
enum:
- incremental
- restate
status:
description: Overall run status derived from its warehouse queries
type: string
enum:
- queued
- running
- failed
- partially-succeeded
- succeeded
runStarted:
description: When query execution began
anyOf:
- format: date-time
type: string
- type: 'null'
dateCreated:
format: date-time
description: When the run record was created
type: string
finishedAt:
description: When the run finished, or null if still in progress
anyOf:
- format: date-time
type: string
- type: 'null'
error:
description: Error message when the run failed
anyOf:
- type: string
- type: 'null'
queryIds:
description: >-
Warehouse query ids for this run; poll each via GET /queries/{id}
for per-query status
type: array
items:
type: string
required:
- id
- idType
- mode
- status
- runStarted
- dateCreated
- finishedAt
- error
- queryIds
additionalProperties: false
AggregatedTableRun:
type: object
properties:
id:
description: The run id (e.g. aftr_...)
type: string
idType:
description: The id type this run materialized
type: string
mode:
description: Whether this run appended new data or rebuilt the table
type: string
enum:
- incremental
- restate
status:
description: Overall run status derived from its warehouse queries
type: string
enum:
- queued
- running
- failed
- partially-succeeded
- succeeded
runStarted:
description: When query execution began
anyOf:
- format: date-time
type: string
- type: 'null'
dateCreated:
format: date-time
description: When the run record was created
type: string
finishedAt:
description: When the run finished, or null if still in progress
anyOf:
- format: date-time
type: string
- type: 'null'
error:
description: Error message when the run failed
anyOf:
- type: string
- type: 'null'
queryIds:
description: >-
Warehouse query ids for this run; poll each via GET /queries/{id}
for per-query status
type: array
items:
type: string
factTableId:
type: string
datasourceId:
type: string
result:
description: Coverage written on success, or null while running/failed
anyOf:
- type: object
properties:
lastMaxTimestamp:
anyOf:
- format: date-time
type: string
- type: 'null'
firstEventDate:
anyOf:
- format: date-time
type: string
- type: 'null'
lastEventDate:
anyOf:
- format: date-time
type: string
- type: 'null'
required:
- lastMaxTimestamp
- firstEventDate
- lastEventDate
additionalProperties: false
- type: 'null'
required:
- id
- idType
- mode
- status
- runStarted
- dateCreated
- finishedAt
- error
- queryIds
- factTableId
- datasourceId
- result
additionalProperties: false
FactMetric:
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
maxLength: 10000
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
projects:
type: array
items:
type: string
tags:
type: array
items:
type: string
datasource:
type: string
metricType:
type: string
enum:
- proportion
- retention
- mean
- quantile
- ratio
- dailyParticipation
- funnel
numerator:
type: object
properties:
factTableId:
type: string
column:
type: string
aggregation:
type: string
enum:
- sum
- max
- count distinct
- hll merge
- kll merge
filters:
deprecated: true
description: >-
Array of Fact Table Filter Ids. Deprecated, use rowFilters
instead.
type: array
items:
type: string
inlineFilters:
deprecated: true
description: >-
Inline filters to apply to the fact table. Keys are column
names, values are arrays of values to filter by. Deprecated, use
rowFilters instead.
type: object
propertyNames:
type: string
additionalProperties:
type: array
items:
type: string
rowFilters:
description: >-
Filters to apply to the rows of the fact table before
aggregation.
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- '>'
- <
- '>='
- <=
- between
- not_between
- in
- not_in
- is_null
- not_null
- is_true
- is_false
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- sql_expr
- saved_filter
values:
description: >-
Not required for is_null, not_null, is_true, is_false
operators. The between and not_between operators take at
most two values, a lower and an upper bound in that order;
leave a bound as an empty string for an open-ended range.
type: array
items:
type: string
column:
description: >-
Required for all operators except sql_expr and
saved_filter.
type: string
required:
- operator
additionalProperties: false
aggregateFilterColumn:
description: >-
Column to use to filter users after aggregation. Either
'$$count' of rows or the name of a numeric column that will be
summed by user. Must specify `aggregateFilter` if using this.
Only can be used with 'retention' and 'proportion' metrics.
type: string
aggregateFilter:
description: >-
Simple comparison operator and value to apply after aggregation
(e.g. '= 10' or '>= 1'). Requires `aggregateFilterColumn`.
type: string
required:
- factTableId
- column
additionalProperties: false
denominator:
type: object
properties:
factTableId:
type: string
column:
type: string
filters:
deprecated: true
description: >-
Array of Fact Table Filter Ids. Deprecated, use rowFilters
instead.
type: array
items:
type: string
inlineFilters:
deprecated: true
description: >-
Inline filters to apply to the fact table. Keys are column
names, values are arrays of values to filter by. Deprecated, use
rowFilters instead.
type: object
propertyNames:
type: string
additionalProperties:
type: array
items:
type: string
rowFilters:
description: >-
Filters to apply to the rows of the fact table before
aggregation.
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- '>'
- <
- '>='
- <=
- between
- not_between
- in
- not_in
- is_null
- not_null
- is_true
- is_false
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- sql_expr
- saved_filter
values:
description: >-
Not required for is_null, not_null, is_true, is_false
operators. The between and not_between operators take at
most two values, a lower and an upper bound in that order;
leave a bound as an empty string for an open-ended range.
type: array
items:
type: string
column:
description: >-
Required for all operators except sql_expr and
saved_filter.
type: string
required:
- operator
additionalProperties: false
required:
- factTableId
- column
additionalProperties: false
inverse:
description: >-
Set to true for things like Bounce Rate, where you want the metric
to decrease
type: boolean
quantileSettings:
description: >-
Controls the settings for quantile metrics (mandatory if metricType
is "quantile")
type: object
properties:
type:
description: >-
Whether the quantile is over unit aggregations or raw event
values
type: string
enum:
- event
- unit
ignoreZeros:
description: >-
If true, zero values will be ignored when calculating the
quantile
type: boolean
quantile:
description: The quantile value (from 0.001 to 0.999)
type: number
minimum: 0.001
maximum: 0.999
multipleOf: 0.001
quantileEventCountColumn:
description: >-
Optional override for the source-column name used to recover
per-row event counts when numerator.aggregation is 'kll merge'.
Defaults to '_n_events'. Only valid for
event-quantile metrics with a 'kll merge' numerator.
type: string
required:
- type
- ignoreZeros
- quantile
additionalProperties: false
funnelSettings:
description: Funnel metric settings (required when metricType is "funnel")
type: object
properties:
steps:
description: Ordered list of funnel steps. Minimum 2 steps required.
minItems: 2
maxItems: 20
type: array
items:
type: object
properties:
name:
description: Display name for the funnel step
type: string
factTableId:
description: The fact table this step draws events from
type: string
rowFilters:
description: >-
Filters that decide whether an event row counts as this
step
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- '>'
- <
- '>='
- <=
- between
- not_between
- in
- not_in
- is_null
- not_null
- is_true
- is_false
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- sql_expr
- saved_filter
values:
description: >-
Not required for is_null, not_null, is_true,
is_false operators. The between and not_between
operators take at most two values, a lower and an
upper bound in that order; leave a bound as an empty
string for an open-ended range.
type: array
items:
type: string
column:
description: >-
Required for all operators except sql_expr and
saved_filter.
type: string
required:
- operator
additionalProperties: false
optional:
description: >-
When true, this step still counts for its own conversion
but does not anchor later steps. Later steps window off
the nearest prior required step (or exposure, for
experiment funnel metrics, when every prior step is
optional).
type: boolean
conversionWindow:
anyOf:
- description: >-
Bounds how long after the nearest prior required step
(or exposure, for the first step / after only-optional
priors of an experiment funnel metric) this step's
event can occur.
type: object
properties:
unit:
type: string
enum:
- weeks
- days
- hours
- minutes
value:
type: number
exclusiveMinimum: 0
required:
- unit
- value
additionalProperties: false
- type: 'null'
required:
- name
- factTableId
- rowFilters
- optional
additionalProperties: false
ordering:
description: Step ordering mode. Only 'sequential' is supported in v1.
type: string
enum:
- sequential
- strict
- unordered
concurrencyWindowSeconds:
description: >-
Out-of-order tolerance between adjacent steps in seconds.
Defaults to 0.
type: integer
minimum: 0
required:
- steps
additionalProperties: false
cappingSettings:
description: Controls how outliers are handled
type: object
properties:
type:
type: string
enum:
- none
- absolute
- percentile
value:
description: >-
When type is absolute, this is the absolute value. When type is
percentile, this is the percentile value (from 0.0 to 1.0).
type: number
ignoreZeros:
description: >-
If true and capping is `percentile`, zeros will be ignored when
calculating the percentile.
type: boolean
required:
- type
additionalProperties: false
lowerCappingSettings:
anyOf:
- description: >-
Independent lower-tail capping settings. Configured separately
from the upper tail, so the type can differ.
type: object
properties:
type:
type: string
enum:
- none
- absolute
- percentile
value:
description: >-
When type is absolute, this is the lower bound. When type is
percentile, this is the lower percentile (from 0.0 to 1.0).
type: number
ignoreZeros:
description: >-
If true and capping is `percentile`, zeros will be ignored
when calculating the percentile.
type: boolean
required:
- type
additionalProperties: false
- type: 'null'
windowSettings:
description: Controls the conversion window for the metric
type: object
properties:
type:
type: string
enum:
- none
- conversion
- lookback
delayValue:
description: >-
Wait this long after experiment exposure before counting
conversions.
type: number
delayUnit:
type: string
enum:
- minutes
- hours
- days
- weeks
windowValue:
type: number
windowUnit:
type: string
enum:
- minutes
- hours
- days
- weeks
required:
- type
additionalProperties: false
priorSettings:
description: Controls the bayesian prior for the metric
type: object
properties:
override:
description: >-
If false, the organization default settings will be used instead
of the other settings in this object
type: boolean
proper:
description: >-
If true, the `mean` and `stddev` will be used, otherwise we will
use an improper flat prior.
type: boolean
mean:
description: >-
The mean of the prior distribution of relative effects in
proportion terms (e.g. 0.01 is 1%)
type: number
stddev:
description: >-
Must be > 0. The standard deviation of the prior distribution of
relative effects in proportion terms.
type: number
required:
- override
- proper
- mean
- stddev
additionalProperties: false
regressionAdjustmentSettings:
description: Controls the regression adjustment (CUPED) settings for the metric
type: object
properties:
override:
description: If false, the organization default settings will be used
type: boolean
enabled:
description: >-
Controls whether or not regression adjustment is applied to the
metric
type: boolean
days:
description: Number of pre-exposure days to use for the regression adjustment
type: number
required:
- override
additionalProperties: false
riskThresholdSuccess:
description: No longer used. Always the default value.
deprecated: true
type: number
riskThresholdDanger:
description: No longer used. Always the default value.
deprecated: true
type: number
displayAsPercentage:
description: >-
If true and the metric is a ratio metric, variation means will be
displayed as a percentage
type: boolean
minPercentChange:
type: number
maxPercentChange:
type: number
minSampleSize:
type: number
targetMDE:
type: number
managedBy:
description: >-
Where this fact metric must be managed from. If not set (empty
string), it can be managed from anywhere.
type: string
enum:
- ''
- api
- admin
- dbt
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
archived:
type: boolean
metricAutoSlices:
description: >-
Array of slice column names that will be automatically included in
metric analysis. This is an enterprise feature.
type: array
items:
type: string
replaces:
description: >-
Ids of older metrics (legacy or fact) that this metric supersedes,
for example the legacy metric it was migrated from. Informational
only - GrowthBook uses it to link the old and new definitions in the
UI and to keep showing results from a snapshot that was created
before an experiment switched to this metric.
type: array
items:
type: string
required:
- id
- name
- description
- owner
- projects
- tags
- datasource
- metricType
- inverse
- cappingSettings
- windowSettings
- priorSettings
- regressionAdjustmentSettings
- riskThresholdSuccess
- riskThresholdDanger
- minPercentChange
- maxPercentChange
- minSampleSize
- targetMDE
- managedBy
- dateCreated
- dateUpdated
additionalProperties: false
MetricAnalysis:
type: object
properties:
id:
description: The ID of the created metric analysis
type: string
status:
description: The status of the analysis (e.g., "running", "completed", "error")
type: string
settings:
type: object
propertyNames:
type: string
additionalProperties: {}
required:
- id
- status
additionalProperties: false
BulkImportError:
type: object
properties:
resourceType:
type: string
enum:
- factTable
- factTableFilter
- factMetric
id:
type: string
message:
type: string
required:
- resourceType
- id
- message
additionalProperties: false
CodeRef:
type: object
properties:
organization:
description: The organization name
type: string
dateUpdated:
format: date-time
description: When the code references were last updated
type: string
feature:
description: Feature identifier
type: string
repo:
description: Repository name
type: string
branch:
description: Branch name
type: string
platform:
description: Source control platform
type: string
enum:
- github
- gitlab
- bitbucket
refs:
type: array
items:
type: object
properties:
filePath:
description: Path to the file containing the reference
type: string
startingLineNumber:
description: Line number where the reference starts
type: integer
lines:
description: The code lines containing the reference
type: string
flagKey:
description: The feature flag key referenced
type: string
required:
- filePath
- startingLineNumber
- lines
- flagKey
additionalProperties: false
required:
- organization
- dateUpdated
- feature
- repo
- branch
- refs
additionalProperties: false
Member:
type: object
properties:
id:
type: string
name:
type: string
email:
type: string
globalRole:
type: string
environments:
type: array
items:
type: string
limitAccessByEnvironment:
type: boolean
additionalRoles:
description: >-
Additional roles granted alongside this one, in the same scope. Each
is granted independently and environment access is the union across
them.
type: array
items:
type: object
properties:
role:
type: string
environments:
type: array
items:
type: string
limitAccessByEnvironment:
type: boolean
required:
- role
- environments
additionalProperties: false
managedbyIdp:
type: boolean
teams:
type: array
items:
type: string
projectRoles:
type: array
items:
type: object
properties:
project:
type: string
role:
type: string
limitAccessByEnvironment:
type: boolean
environments:
type: array
items:
type: string
additionalRoles:
description: >-
Additional roles granted alongside this one, in the same
scope. Each is granted independently and environment access is
the union across them.
type: array
items:
type: object
properties:
role:
type: string
environments:
type: array
items:
type: string
limitAccessByEnvironment:
type: boolean
required:
- role
- environments
additionalProperties: false
required:
- project
- role
- limitAccessByEnvironment
- environments
additionalProperties: false
lastLoginDate:
format: date-time
type: string
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
required:
- id
- email
- globalRole
additionalProperties: false
Query:
type: object
properties:
id:
type: string
organization:
type: string
datasource:
type: string
language:
type: string
query:
type: string
queryType:
type: string
createdAt:
type: string
startedAt:
type: string
status:
type: string
enum:
- running
- queued
- failed
- partially-succeeded
- succeeded
externalId:
type: string
dependencies:
type: array
items:
type: string
runAtEnd:
type: boolean
required:
- id
- organization
- datasource
- language
- query
- queryType
- createdAt
- startedAt
- status
- externalId
- dependencies
- runAtEnd
additionalProperties: false
Settings:
type: object
properties:
confidenceLevel:
type: number
northStar:
anyOf:
- type: object
properties:
title:
type: string
metricIds:
type: array
items:
type: string
additionalProperties: false
- type: 'null'
metricDefaults:
type: object
properties:
priorSettings:
type: object
properties:
override:
type: boolean
proper:
type: boolean
mean:
type: number
stddev:
type: number
required:
- override
- proper
- mean
- stddev
additionalProperties: false
minimumSampleSize:
type: number
maxPercentageChange:
type: number
minPercentageChange:
type: number
targetMDE:
type: number
additionalProperties: false
pastExperimentsMinLength:
type: number
metricAnalysisDays:
type: number
updateSchedule:
anyOf:
- type: object
properties:
type:
type: string
enum:
- cron
- never
- stale
cron:
anyOf:
- type: string
- type: 'null'
hours:
anyOf:
- type: number
- type: 'null'
analysisEndDateMode:
type: string
enum:
- runTime
- lag
- fixedTime
analysisEndDateLagHours:
anyOf:
- type: number
- type: 'null'
analysisEndDateTime:
anyOf:
- type: string
pattern: ^([01]\d|2[0-3]):[0-5]\d$
- type: 'null'
additionalProperties: false
- type: 'null'
multipleExposureMinPercent:
type: number
defaultRole:
type: object
properties:
role:
type: string
limitAccessByEnvironment:
type: boolean
environments:
type: array
items:
type: string
additionalProperties: false
statsEngine:
type: string
pValueThreshold:
type: number
regressionAdjustmentEnabled:
type: boolean
regressionAdjustmentDays:
type: number
sequentialTestingEnabled:
type: boolean
sequentialTestingTuningParameter:
type: number
attributionModel:
type: string
enum:
- firstExposure
- experimentDuration
- lookbackOverride
targetMDE:
type: number
delayHours:
type: number
windowType:
type: string
windowHours:
type: number
winRisk:
description: No longer used. Always the default value.
deprecated: true
type: number
loseRisk:
description: No longer used. Always the default value.
deprecated: true
type: number
secureAttributeSalt:
type: string
killswitchConfirmation:
type: boolean
featureKillSwitchBehavior:
type: string
enum:
- 'off'
- warn
requireReviews:
type: array
items:
$ref: '#/components/schemas/RequireReviewRule'
approvalFlows:
type: object
properties:
savedGroups:
type: array
items:
$ref: '#/components/schemas/SavedGroupApprovalRule'
required:
- savedGroups
additionalProperties: false
targetingReviewMode:
type: array
items:
$ref: '#/components/schemas/TargetingReviewRule'
restApiBypassesReviews:
type: boolean
requireRebaseBeforePublish:
type: boolean
revertsBypassApproval:
type: boolean
maxConcurrentDrafts:
type: number
featureKeyExample:
type: string
featureRegexValidator:
type: string
sparseJSONRulesByDefault:
type: boolean
banditScheduleValue:
type: number
banditScheduleUnit:
type: string
enum:
- hours
- days
banditBurnInValue:
type: number
banditBurnInUnit:
type: string
enum:
- hours
- days
experimentMinLengthDays:
type: number
experimentMaxLengthDays:
anyOf:
- type: number
- type: 'null'
preferredEnvironment:
anyOf:
- type: string
- type: 'null'
maxMetricSliceLevels:
type: number
topValuesLookbackValue:
type: number
topValuesLookbackUnit:
type: string
enum:
- days
required:
- confidenceLevel
- northStar
- metricDefaults
- pastExperimentsMinLength
- metricAnalysisDays
- updateSchedule
- multipleExposureMinPercent
- defaultRole
- statsEngine
- pValueThreshold
- regressionAdjustmentEnabled
- regressionAdjustmentDays
- sequentialTestingEnabled
- sequentialTestingTuningParameter
- attributionModel
- targetMDE
- delayHours
- windowType
- windowHours
- winRisk
- loseRisk
- secureAttributeSalt
- killswitchConfirmation
- requireReviews
- approvalFlows
- featureKeyExample
- featureRegexValidator
- banditScheduleValue
- banditScheduleUnit
- banditBurnInValue
- banditBurnInUnit
- experimentMinLengthDays
additionalProperties: false
RequireReviewRule:
type: object
properties:
requireReviewOn:
type: boolean
projects:
type: array
items:
type: string
resetReviewOnChange:
type: boolean
environments:
type: array
items:
type: string
featureRequireEnvironmentReview:
type: boolean
featureRequireMetadataReview:
type: boolean
blockSelfApproval:
type: boolean
autopublishOnApproval:
type: boolean
requiredApproverTeams:
type: array
items:
type: string
additionalProperties: false
SavedGroupApprovalRule:
type: object
properties:
required:
type: boolean
projects:
type: array
items:
type: string
resetReviewOnChange:
type: boolean
requireMetadataReview:
type: boolean
blockSelfApproval:
type: boolean
autopublishOnApproval:
type: boolean
requiredApproverTeams:
type: array
items:
type: string
required:
- required
additionalProperties: false
TargetingReviewRule:
type: object
properties:
projects:
description: >-
Targeting Project IDs this rule applies to. An empty list is the
organization-wide default.
type: array
items:
type: string
mode:
description: >-
`strict`: a Feature Flag delivered into these Targeting Projects
must also satisfy their approval requirements, and a Targeting
Project with a rule of its own must be approved by one of its
reviewers. `loose`: only the flag's primary project governs
approvals.
type: string
enum:
- strict
- loose
required:
- projects
- mode
additionalProperties: false
RequireReviewRuleInput:
type: object
properties:
requireReviewOn:
type: boolean
projects:
type: array
items:
type: string
resetReviewOnChange:
type: boolean
environments:
type: array
items:
type: string
featureRequireEnvironmentReview:
type: boolean
featureRequireMetadataReview:
type: boolean
blockSelfApproval:
type: boolean
autopublishOnApproval:
type: boolean
requiredApproverTeams:
type: array
items:
type: string
required:
- requireReviewOn
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.checklist
- 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
InformationSchemaTable:
type: object
properties:
id:
type: string
datasourceId:
type: string
informationSchemaId:
type: string
tableName:
type: string
tableSchema:
type: string
databaseName:
type: string
columns:
type: array
items:
type: object
properties:
columnName:
type: string
dataType:
type: string
required:
- columnName
- dataType
additionalProperties: false
refreshMS:
type: number
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
required:
- id
- datasourceId
- informationSchemaId
- tableName
- tableSchema
- databaseName
- columns
- refreshMS
- dateCreated
- dateUpdated
additionalProperties: false
RampSchedule:
type: object
properties:
id:
description: Unique identifier (rs_ prefix)
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
name:
type: string
entityType:
type: string
enum:
- feature
entityId:
type: string
targets:
description: Controlled entity references
type: array
items:
type: object
properties:
id:
type: string
entityType:
type: string
enum:
- feature
entityId:
type: string
ruleId:
anyOf:
- type: string
- type: 'null'
environment:
deprecated: true
description: >-
Legacy disambiguator used alongside `ruleId` for pre-v2 ramps.
May be null on newer targets.
anyOf:
- type: string
- type: 'null'
status:
type: string
enum:
- pending-join
- active
activatingRevisionVersion:
description: >-
Feature revision version that activates this ramp; cleared
once published
anyOf:
- type: integer
- type: 'null'
required:
- id
- entityType
- entityId
- status
additionalProperties: false
startActions:
description: >-
Actions that restore controlled rules to their pre-ramp state.
Applied when rolling back or jumping to start, and the base every
step accumulates on; the only place a plan can set hashAttribute,
seed or hashVersion.
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'
required:
- ruleId
additionalProperties: false
required:
- targetType
- targetId
- patch
additionalProperties: false
steps:
description: Ordered ramp steps
type: array
items:
type: object
properties:
interval:
description: >-
Hold duration in seconds before this step's gates are
evaluated. null = no time gate (advance as soon as
holdConditions clear).
anyOf:
- type: number
exclusiveMinimum: 0
- type: 'null'
approvalNotes:
anyOf:
- type: string
- type: 'null'
monitored:
description: >-
When true, this step runs A/B traffic analysis while active.
Treatment = [0, coverage), control = [0.5, 0.5+coverage). Arms
are equal-sized and non-adjacent: step-ups only add users,
never reassign existing ones. The UI caps monitored-step
coverage at 0.5 so control end never exceeds 1.0. The SDK uses
explicit hash ranges on the experiment rule to prevent
bucketing shifts across monitored/unmonitored transitions.
type: boolean
holdConditions:
type: object
properties:
minSampleSize:
type: integer
exclusiveMinimum: 0
requiresApproval:
type: boolean
additionalProperties: false
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'
required:
- ruleId
additionalProperties: false
required:
- targetType
- targetId
- patch
additionalProperties: false
required:
- interval
- actions
additionalProperties: false
endActions:
description: >-
Actions applied on top of all step patches when the ramp completes.
Represents the final desired rule state.
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'
required:
- ruleId
additionalProperties: false
required:
- targetType
- targetId
- patch
additionalProperties: false
startDate:
description: >-
When the ramp fires. Absent/null means immediately on publish; set
to a future datetime to delay start and keep the rule disabled until
that time.
anyOf:
- type: string
format: date-time
- type: 'null'
cutoffDate:
description: >-
Rule-level kill date. When reached, the ramp is completed and the
rule is disabled (enabled=false). Use for time-boxed rules that must
stop serving on a fixed date regardless of ramp progress. Set to
null to clear.
anyOf:
- type: string
format: date-time
- type: 'null'
requiresStartApproval:
description: >-
When true, the ramp holds at step -1 with its rule disabled (zero
traffic) until a human approves the start via /actions/approve-step.
Composes with startDate ('hold until approved, then arm for that
date').
type: boolean
startApprovedAt:
description: >-
When the current launch's start was approved. Cleared on every
return to step -1 (publish, rollback), re-arming the approval gate.
anyOf:
- type: string
format: date-time
- type: 'null'
status:
type: string
enum:
- pending
- ready
- running
- paused
- completed
- rolled-back
currentStepIndex:
description: Index of current step; -1 = not yet started
type: integer
minimum: -1
startedAt:
anyOf:
- type: string
format: date-time
- type: 'null'
phaseStartedAt:
description: >-
Anchor for cumulative interval timing; resets after each approval
gate is satisfied
anyOf:
- type: string
format: date-time
- type: 'null'
pausedAt:
anyOf:
- type: string
format: date-time
- type: 'null'
nextStepAt:
description: >-
When the current step's time gate elapses; null for steps with no
interval (pure approval gates) and terminal states
anyOf:
- type: string
format: date-time
- type: 'null'
nextProcessAt:
anyOf:
- type: string
format: date-time
- type: 'null'
elapsedMs:
description: Milliseconds since startedAt (computed at response time, not stored)
anyOf:
- type: integer
- type: 'null'
lockdownConfig:
type: object
properties:
mode:
type: string
enum:
- none
- locked
required:
- mode
additionalProperties: false
monitoringConfig:
anyOf:
- 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
- type: 'null'
experimentHealthAction:
type: string
enum:
- rollback
- hold
- warn
currentStepEnteredAt:
anyOf:
- type: string
format: date-time
- type: 'null'
stepApproval:
description: >-
Approval record for the current step. Valid only while
`stepApproval.stepIndex === currentStepIndex`.
anyOf:
- type: object
properties:
stepIndex:
description: Index of the step that was approved.
type: integer
approvedAt:
description: When the approval was granted.
type: string
format: date-time
approvedBy:
description: >-
Who approved: the approver's user ID, or the API key's ID
when a key approved as itself.
type: string
approvedByUser:
description: The approver, with an API key's name.
$ref: '#/components/schemas/EventUser'
context:
description: Surface through which the approval was granted.
type: string
enum:
- ui
- api
required:
- stepIndex
- approvedAt
- approvedBy
- context
additionalProperties: false
- type: 'null'
awaitingApproval:
description: >-
Computed at read time: whether a human approval is the gate blocking
the schedule right now — either the start-approval gate
(`requiresStartApproval` before step 0) or the current step's
`holdConditions.requiresApproval` once its time hold (if any) has
elapsed. Paused schedules report `false` (the pause is the blocking
gate). For monitored steps the approve-step endpoint may still
reject an approval until analysis-based gates clear.
type: boolean
monitoringStartDate:
description: >-
When the monitored section most recently started (first monitored
step entered). Used for no-traffic grace period gating.
anyOf:
- type: string
format: date-time
- type: 'null'
lastRollbackAt:
anyOf:
- type: string
format: date-time
- type: 'null'
lastRollbackReason:
anyOf:
- type: string
- type: 'null'
monitoringStatus:
description: Read-only monitoring status. Present when monitoringConfig is set.
anyOf:
- type: object
properties:
safeRolloutId:
anyOf:
- type: string
- type: 'null'
monitoringMode:
description: >-
User-selected monitoring mode. `auto` schedules snapshots
automatically; `manual` requires clicking Update.
type: string
enum:
- auto
- manual
autoUpdate:
description: >-
Legacy alias for auto-update behavior. Prefer
`monitoringMode` (`auto` means true, `manual` means false).
type: boolean
effectiveAutoUpdate:
description: >-
Computed runtime flag. True only when monitoring mode is
auto and schedule state allows automatic snapshot
scheduling.
type: boolean
blockedReason:
description: >-
When `effectiveAutoUpdate` is false, this describes the
computed reason auto-updates are currently blocked.
anyOf:
- type: string
- type: 'null'
nextSnapshotAt:
description: When the next automatic snapshot query will run
anyOf:
- type: string
format: date-time
- type: 'null'
currentStepMonitored:
description: Whether the step at currentStepIndex has monitoring enabled
type: boolean
required:
- monitoringMode
- autoUpdate
- effectiveAutoUpdate
- currentStepMonitored
additionalProperties: false
- type: 'null'
required:
- id
- dateCreated
- dateUpdated
- name
- entityType
- entityId
- targets
- steps
- status
- currentStepIndex
- nextStepAt
- awaitingApproval
additionalProperties: false
MatchedRampSchedule:
type: object
properties:
id:
type: string
featureId:
type: string
result:
type: string
enum:
- applied
- skipped
message:
type: string
required:
- id
- featureId
- result
additionalProperties: false
Report:
type: object
properties:
id:
type: string
dateCreated:
type: string
dateUpdated:
type: string
title:
type: string
description:
type: string
type:
description: >-
Report type. `experiment-snapshot` is the current shape and is what
`POST /reports` always creates. `experiment` is a deprecated legacy
shape that is read-only through this API; it cannot be created or
refreshed and is preserved only for backward compatibility when
reading reports created before the new shape existed.
type: string
enum:
- experiment-snapshot
- experiment
status:
description: >-
UI lifecycle marker. Note: this does NOT control public shareability
— see `shareLevel` for visibility controls.
type: string
enum:
- published
- private
shareLevel:
description: >-
Visibility of the report. `private` (default) restricts access to
the API caller and admins. `organization` makes it visible to all
members of the organization in the GrowthBook UI. `public`
additionally exposes it via a shareable URL (returned as
`shareUrl`); anyone with the URL can view it without authentication.
type: string
enum:
- public
- organization
- private
shareUrl:
description: >-
Public URL for viewing the report. Only present when `shareLevel` is
`public`.
type: string
experimentId:
type: string
owner:
description: >-
The userId of the report owner. Absent for reports created before
owner attribution existed.
type: string
ownerEmail:
description: >-
The email address of the owner, when the owner can be resolved to a
known user.
type: string
snapshotId:
description: Snapshot ID (experiment-snapshot type only)
type: string
snapshotStatus:
description: Status of the latest snapshot (poll this after refresh)
type: string
enum:
- running
- success
- error
snapshotError:
description: Error message if snapshot failed
type: string
analysisSettings:
type: object
properties:
statsEngine:
type: string
enum:
- bayesian
- frequentist
goalMetrics:
type: array
items:
type: string
secondaryMetrics:
type: array
items:
type: string
guardrailMetrics:
type: array
items:
type: string
activationMetric:
type: string
metricOverrides:
description: Per-metric window, prior, and regression-adjustment overrides
type: array
items:
type: object
properties:
id:
type: string
windowType:
type: string
enum:
- conversion
- lookback
- ''
windowHours:
type: number
delayHours:
type: number
properPriorOverride:
type: boolean
properPriorEnabled:
type: boolean
properPriorMean:
type: number
properPriorStdDev:
type: number
exclusiveMinimum: 0
regressionAdjustmentOverride:
type: boolean
regressionAdjustmentEnabled:
type: boolean
regressionAdjustmentDays:
type: number
winRisk:
deprecated: true
description: No longer used. Accepted and ignored.
type: number
loseRisk:
deprecated: true
description: No longer used. Accepted and ignored.
type: number
required:
- id
additionalProperties: false
customMetricSlices:
description: Custom metric slice definitions
type: array
items:
type: object
properties:
slices:
type: array
items:
type: object
properties:
column:
type: string
levels:
type: array
items:
type: string
required:
- column
- levels
additionalProperties: false
required:
- slices
additionalProperties: false
dimension:
type: string
differenceType:
description: >-
How lifts are expressed in results: `relative` (% change),
`absolute` (raw difference), or `scaled` (scaled impact)
type: string
enum:
- relative
- absolute
- scaled
dateStarted:
format: date-time
type: string
dateEnded:
format: date-time
type: string
regressionAdjustmentEnabled:
type: boolean
sequentialTestingEnabled:
type: boolean
sequentialTestingTuningParameter:
description: Tuning parameter for sequential testing (frequentist only)
type: number
attributionModel:
description: >-
Metric conversion window attribution model: `firstExposure`,
`experimentDuration`, or `lookbackOverride`
type: string
enum:
- firstExposure
- experimentDuration
- lookbackOverride
lookbackOverride:
description: >-
Lookback window used when `attributionModel` is
`lookbackOverride`
anyOf:
- type: object
properties:
type:
type: string
const: date
value: {}
required:
- type
- value
additionalProperties: false
- type: object
properties:
type:
type: string
const: window
value:
type: number
minimum: 0
valueUnit:
type: string
enum:
- minutes
- hours
- days
- weeks
required:
- type
- value
- valueUnit
additionalProperties: false
trackingKey:
description: Tracking key used to identify experiment exposures
type: string
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:
deprecated: true
description: 'Deprecated: use `exposureQuery`.'
type: string
segment:
description: Segment ID to filter users by
type: string
queryFilter:
description: Raw SQL WHERE clause added to the exposure query
type: string
skipPartialData:
description: >-
When true, exclude users who have not completed the full
conversion window
type: boolean
additionalProperties: false
experimentMetadata:
type: object
properties:
type:
description: Experiment type
type: string
enum:
- standard
- multi-armed-bandit
- holdout
variations:
description: >-
Variation metadata with current traffic weights — use to label
result columns
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
key:
type: string
weight:
description: Traffic weight (0–1)
type: number
required:
- id
- name
- key
- weight
additionalProperties: false
phases:
description: Experiment phases
type: array
items:
type: object
properties:
name:
type: string
dateStarted:
type: string
dateEnded:
type: string
coverage:
description: Traffic coverage (0–1)
type: number
additionalProperties: false
additionalProperties: false
results:
$ref: '#/components/schemas/ExperimentResults'
required:
- id
- dateCreated
- dateUpdated
- title
- description
- type
additionalProperties: false
Namespace:
type: object
properties:
id:
description: The unique internal identifier for the namespace (e.g. 'ns-abc123').
type: string
displayName:
description: Human-readable display name.
type: string
description:
type: string
status:
type: string
enum:
- active
- inactive
format:
description: >-
Namespace format. 'multiRange' supports multiple ranges per
experiment and a configurable hash attribute.
type: string
enum:
- legacy
- multiRange
hashAttribute:
description: >-
The user attribute used to assign bucket membership. Only present on
multiRange namespaces.
type: string
seed:
description: >-
The seed used for bucket hashing. Changing this re-randomizes which
traffic is eligible for which experiment. Use the rotateSeed
endpoint to change it.
type: string
required:
- id
- displayName
- description
- status
- format
additionalProperties: false
NamespaceExperimentMember:
type: object
properties:
id:
description: The internal experiment ID.
type: string
name:
description: Display name of the experiment.
type: string
trackingKey:
description: The experiment tracking key used by the SDK.
type: string
status:
description: The current status of the experiment.
type: string
enum:
- draft
- running
- stopped
ranges:
description: >-
The ranges claimed within this namespace, as [start, end] pairs
between 0 and 1.
type: array
items:
type: array
prefixItems:
- type: number
- type: number
required:
- id
- name
- trackingKey
- status
- ranges
additionalProperties: false
Dashboard:
type: object
properties:
id:
type: string
uid:
type: string
organization:
type: string
experimentId:
type: string
isDefault:
type: boolean
isDeleted:
type: boolean
userId:
type: string
editLevel:
type: string
enum:
- published
- private
shareLevel:
type: string
enum:
- published
- private
enableAutoUpdates:
type: boolean
updateSchedule:
anyOf:
- type: object
properties:
type:
type: string
const: stale
hours:
type: number
required:
- type
- hours
additionalProperties: false
- type: object
properties:
type:
type: string
const: cron
cron:
type: string
required:
- type
- cron
additionalProperties: false
title:
type: string
globalControls:
type: object
properties:
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
projects:
type: array
items:
type: string
experimentSearchString:
type: string
additionalProperties: false
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
grid:
type: object
properties:
cols:
default: 24
type: integer
minimum: 1
maximum: 24
rowHeight:
default: 40
type: integer
minimum: 8
required:
- cols
- rowHeight
additionalProperties: false
projects:
type: array
items:
type: string
nextUpdate:
type: string
format: date-time
lastUpdated:
type: string
format: date-time
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
blocks:
type: array
items:
anyOf:
- type: object
properties:
organization:
type: string
id:
type: string
uid:
type: string
type:
type: string
const: metric-explorer
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
factMetricId:
type: string
visualizationType:
type: string
enum:
- histogram
- bigNumber
- timeseries
valueType:
type: string
enum:
- avg
- sum
metricAnalysisId:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonMetricAnalysisId:
type: string
analysisSettings:
type: object
properties:
userIdType:
type: string
lookbackDays:
type: number
populationType:
type: string
enum:
- metric
- factTable
- exposureQuery
- population
- segment
populationId:
anyOf:
- type: string
- type: 'null'
additionalNumeratorFilters:
type: array
items:
type: string
additionalDenominatorFilters:
type: array
items:
type: string
startDate:
type: string
endDate:
type: string
required:
- userIdType
- lookbackDays
- populationType
- populationId
- startDate
- endDate
additionalProperties: false
required:
- organization
- id
- uid
- type
- title
- description
- factMetricId
- visualizationType
- valueType
- metricAnalysisId
- analysisSettings
additionalProperties: false
- type: object
properties:
organization:
type: string
id:
type: string
uid:
type: string
type:
type: string
const: markdown
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
content:
type: string
required:
- organization
- id
- uid
- type
- title
- description
- content
additionalProperties: false
- type: object
properties:
organization:
type: string
id:
type: string
uid:
type: string
type:
type: string
const: experiment-metadata
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
showDescription:
type: boolean
showHypothesis:
type: boolean
showVariationImages:
type: boolean
variationIds:
type: array
items:
type: string
required:
- organization
- id
- uid
- type
- title
- description
- experimentId
- showDescription
- showHypothesis
- showVariationImages
additionalProperties: false
- type: object
properties:
organization:
type: string
id:
type: string
uid:
type: string
type:
type: string
const: experiment-metric
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
metricIds:
type: array
items:
type: string
variationIds:
type: array
items:
type: string
baselineRow:
type: number
differenceType:
type: string
enum:
- absolute
- relative
- scaled
columnsFilter:
type: array
items:
type: string
enum:
- Metric & Variation Names
- Baseline Average
- Variation Averages
- Chance to Win
- CI Graph
- Lift
sliceTagsFilter:
type: array
items:
type: string
metricTagFilter:
type: array
items:
type: string
sortBy:
anyOf:
- type: string
enum:
- metrics
- metricTags
- significance
- change
- type: 'null'
sortDirection:
anyOf:
- type: string
enum:
- asc
- desc
- type: 'null'
required:
- organization
- id
- uid
- type
- title
- description
- snapshotId
- experimentId
- metricIds
- variationIds
- baselineRow
- differenceType
- columnsFilter
- sliceTagsFilter
- metricTagFilter
- sortBy
- sortDirection
additionalProperties: false
- type: object
properties:
organization:
type: string
id:
type: string
uid:
type: string
type:
type: string
const: metric-experiments
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
metricId:
type: string
projects:
type: array
items:
type: string
experimentSearchString:
type: string
differenceType:
type: string
enum:
- absolute
- relative
- scaled
bandits:
type: boolean
startDateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
endDateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
columns:
type: array
items:
type: object
properties:
id:
type: string
visible:
type: boolean
required:
- id
- visible
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
required:
- organization
- id
- uid
- type
- title
- description
- metricId
- projects
- experimentSearchString
- differenceType
- bandits
additionalProperties: false
- type: object
properties:
organization:
type: string
id:
type: string
uid:
type: string
type:
type: string
const: experiments-scaled-impact
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
projects:
type: array
items:
type: string
experimentSearchString:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
metricId:
type: string
required:
- organization
- id
- uid
- type
- title
- description
- dateRange
- projects
- metricId
additionalProperties: false
- type: object
properties:
organization:
type: string
id:
type: string
uid:
type: string
type:
type: string
const: experiments-win-rate
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
projects:
type: array
items:
type: string
experimentSearchString:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
showProjectBreakdown:
type: boolean
required:
- organization
- id
- uid
- type
- title
- description
- dateRange
- projects
- showProjectBreakdown
additionalProperties: false
- type: object
properties:
organization:
type: string
id:
type: string
uid:
type: string
type:
type: string
const: experiments-status
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
projects:
type: array
items:
type: string
experimentSearchString:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
projects:
type: boolean
experimentSearchString:
type: boolean
additionalProperties: false
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- organization
- id
- uid
- type
- title
- description
- dateRange
- projects
additionalProperties: false
- type: object
properties:
organization:
type: string
id:
type: string
uid:
type: string
type:
type: string
const: experiment-dimension
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
dimensionId:
type: string
dimensionValues:
type: array
items:
type: string
metricIds:
type: array
items:
type: string
variationIds:
type: array
items:
type: string
baselineRow:
type: number
differenceType:
type: string
enum:
- absolute
- relative
- scaled
columnsFilter:
type: array
items:
type: string
enum:
- Metric & Variation Names
- Baseline Average
- Variation Averages
- Chance to Win
- CI Graph
- Lift
metricTagFilter:
type: array
items:
type: string
sortBy:
anyOf:
- type: string
enum:
- metrics
- metricTags
- significance
- change
- type: 'null'
sortDirection:
anyOf:
- type: string
enum:
- asc
- desc
- type: 'null'
required:
- organization
- id
- uid
- type
- title
- description
- snapshotId
- experimentId
- dimensionId
- dimensionValues
- metricIds
- variationIds
- baselineRow
- differenceType
- columnsFilter
- metricTagFilter
- sortBy
- sortDirection
additionalProperties: false
- type: object
properties:
organization:
type: string
id:
type: string
uid:
type: string
type:
type: string
const: experiment-time-series
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
metricId:
type: string
metricIds:
type: array
items:
type: string
variationIds:
type: array
items:
type: string
differenceType:
type: string
enum:
- absolute
- relative
- scaled
sliceTagsFilter:
type: array
items:
type: string
metricTagFilter:
type: array
items:
type: string
sortBy:
anyOf:
- type: string
enum:
- metrics
- metricTags
- significance
- change
- type: 'null'
sortDirection:
anyOf:
- type: string
enum:
- asc
- desc
- type: 'null'
required:
- organization
- id
- uid
- type
- title
- description
- snapshotId
- experimentId
- metricIds
- variationIds
- differenceType
- sliceTagsFilter
- metricTagFilter
- sortBy
- sortDirection
additionalProperties: false
- type: object
properties:
organization:
type: string
id:
type: string
uid:
type: string
type:
type: string
const: experiment-traffic
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
experimentId:
type: string
showTable:
type: boolean
showTimeseries:
type: boolean
required:
- organization
- id
- uid
- type
- title
- description
- experimentId
- showTable
- showTimeseries
additionalProperties: false
- type: object
properties:
organization:
type: string
id:
type: string
uid:
type: string
type:
type: string
const: sql-explorer
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
savedQueryId:
type: string
dataVizConfigIndex:
type: number
blockConfig:
type: array
items:
type: string
required:
- organization
- id
- uid
- type
- title
- description
- savedQueryId
- blockConfig
additionalProperties: false
- type: object
properties:
organization:
type: string
id:
type: string
uid:
type: string
type:
type: string
const: metric-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
explorerAnalysisId:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: metric
dataset:
type: object
properties:
type:
type: string
const: metric
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: metric
metricId:
type: string
unit:
anyOf:
- type: string
- type: 'null'
denominatorUnit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- metricId
- unit
- denominatorUnit
additionalProperties: false
required:
- type
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
required:
- organization
- id
- uid
- type
- title
- description
- explorerAnalysisId
- config
additionalProperties: false
- type: object
properties:
organization:
type: string
id:
type: string
uid:
type: string
type:
type: string
const: fact-table-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
explorerAnalysisId:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: fact_table
dataset:
type: object
properties:
type:
type: string
const: fact_table
factTableId:
anyOf:
- type: string
- type: 'null'
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: fact_table
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
required:
- type
- factTableId
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
required:
- organization
- id
- uid
- type
- title
- description
- explorerAnalysisId
- config
additionalProperties: false
- type: object
properties:
organization:
type: string
id:
type: string
uid:
type: string
type:
type: string
const: data-source-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
explorerAnalysisId:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: data_source
dataset:
type: object
properties:
type:
type: string
const: data_source
table:
type: string
path:
type: string
timestampColumn:
type: string
columnTypes:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- string
- number
- date
- boolean
- other
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: data_source
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
required:
- type
- table
- path
- timestampColumn
- columnTypes
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
required:
- organization
- id
- uid
- type
- title
- description
- explorerAnalysisId
- config
additionalProperties: false
- type: object
properties:
organization:
type: string
id:
type: string
uid:
type: string
type:
type: string
const: sql-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
explorerAnalysisId:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: sql
dataset:
type: object
properties:
type:
type: string
const: sql
sql:
type: string
timestampColumn:
anyOf:
- type: string
- type: 'null'
columnTypes:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- string
- number
- date
- boolean
- other
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: sql
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
hiddenColumns:
type: array
items:
type: string
required:
- type
- sql
- timestampColumn
- columnTypes
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
required:
- organization
- id
- uid
- type
- title
- description
- explorerAnalysisId
- config
additionalProperties: false
- type: object
properties:
organization:
type: string
id:
type: string
uid:
type: string
type:
type: string
const: funnel-exploration
title:
type: string
description:
type: string
snapshotId:
type: string
layout:
type: object
properties:
x:
type: integer
minimum: 0
maximum: 23
'y':
type: integer
minimum: 0
w:
type: integer
minimum: 1
maximum: 24
h:
type: integer
minimum: 1
static:
type: boolean
required:
- x
- 'y'
- w
- h
additionalProperties: false
explorerAnalysisId:
type: string
comparison:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum:
- previousPeriod
- previousPeriodMatchDayOfWeek
- previousYear
- previousYearMatchDayOfWeek
- custom
previousTimeFrame:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
required:
- enabled
additionalProperties: false
comparisonExplorerAnalysisId:
type: string
globalControlSettings:
type: object
properties:
dateRange:
type: boolean
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: funnel
dataset:
type: object
properties:
type:
type: string
const: funnel
unit:
anyOf:
- type: string
- type: 'null'
steps:
maxItems: 20
type: array
items:
type: object
properties:
name:
type: string
factTableId:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
optional:
type: boolean
conversionWindow:
anyOf:
- type: object
properties:
unit:
type: string
enum:
- weeks
- days
- hours
- minutes
value:
type: number
exclusiveMinimum: 0
required:
- unit
- value
additionalProperties: false
- type: 'null'
required:
- name
- factTableId
- rowFilters
- optional
additionalProperties: false
concurrencyWindowSeconds:
type: integer
minimum: 0
yAxisScale:
type: string
enum:
- count
- percent
required:
- type
- unit
- steps
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
linkedFunnelMetricId:
anyOf:
- type: string
- type: 'null'
required:
- organization
- id
- uid
- type
- title
- description
- explorerAnalysisId
- config
additionalProperties: false
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
required:
- id
- uid
- organization
- isDefault
- isDeleted
- userId
- editLevel
- shareLevel
- enableAutoUpdates
- title
- dateCreated
- dateUpdated
- blocks
- owner
additionalProperties: false
ContextualBandit:
type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
name:
type: string
description:
type: string
project:
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
tags:
type: array
items:
type: string
archived:
type: boolean
status:
type: string
enum:
- draft
- running
- stopped
dateStarted:
type: string
format: date-time
dateStopped:
type: string
format: date-time
trackingKey:
type: string
hashAttribute:
type: string
variations:
type: array
items:
type: object
properties:
id:
type: string
key:
type: string
name:
type: string
description:
type: string
status:
type: string
enum:
- active
- pending
required:
- id
- key
- name
additionalProperties: false
datasource:
type: string
contextualBanditQueryId:
type: string
coverage:
type: number
minimum: 0
maximum: 1
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
seed:
type: string
variationWeights:
type: array
items:
type: object
properties:
variationId:
type: string
weight:
type: number
required:
- variationId
- weight
additionalProperties: false
currentLeafWeights:
type: array
items:
type: object
properties:
leafId:
type: integer
condition:
type: object
propertyNames:
type: string
additionalProperties: {}
weights:
type: array
items:
type: object
properties:
variationId:
type: string
weight:
type: number
required:
- variationId
- weight
additionalProperties: false
required:
- leafId
- condition
- weights
additionalProperties: false
banditVersion:
type: integer
minimum: 0
contextualAttributes:
type: array
items:
type: string
decisionMetric:
type: string
minUsersPerLeaf:
type: integer
exclusiveMinimum: 0
maxLeaves:
type: integer
exclusiveMinimum: 0
priorSampleSize:
type: integer
minimum: 0
holdoutPercent:
type: number
minimum: 0
maximum: 0.5
banditModelVersion:
type: integer
minimum: 0
scheduleValue:
type: number
scheduleUnit:
type: string
enum:
- days
- hours
burnInValue:
type: number
burnInUnit:
type: string
enum:
- days
- hours
conversionWindowValue:
anyOf:
- type: number
- type: 'null'
conversionWindowUnit:
anyOf:
- type: string
enum:
- hours
- days
- type: 'null'
stage:
type: string
enum:
- explore
- exploit
- paused
stageDateStarted:
type: string
format: date-time
analysisSummary:
type: object
properties:
snapshotId:
type: string
health:
type: object
properties:
srm:
anyOf:
- type: number
- type: 'null'
totalUsers:
type: number
multipleExposures:
type: number
variationIds:
type: array
items:
type: string
required:
- srm
- totalUsers
additionalProperties: false
required:
- snapshotId
additionalProperties: false
autoSnapshots:
type: boolean
nextSnapshotAttempt:
type: string
format: date-time
hasVisualChangesets:
type: boolean
required:
- id
- dateCreated
- dateUpdated
- name
- owner
- tags
- archived
- status
- trackingKey
- hashAttribute
- variations
- datasource
- contextualBanditQueryId
- seed
- currentLeafWeights
- banditVersion
- contextualAttributes
- minUsersPerLeaf
- maxLeaves
- priorSampleSize
- holdoutPercent
- banditModelVersion
additionalProperties: false
ContextualBanditQuery:
type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
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
datasourceId:
type: string
name:
type: string
description:
type: string
userIdType:
type: string
query:
type: string
targetingAttributeColumns:
type: array
items:
type: string
required:
- id
- dateCreated
- dateUpdated
- owner
- datasourceId
- name
- userIdType
- query
- targetingAttributeColumns
additionalProperties: false
Interleaving:
type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
name:
type: string
description:
type: string
project:
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
tags:
type: array
items:
type: string
archived:
type: boolean
status:
type: string
enum:
- draft
- running
- stopped
dateStarted:
type: string
format: date-time
dateStopped:
type: string
format: date-time
key:
description: The key your code passes to `interleave()` as `key`
type: string
trackingKey:
description: The `experiment_id` recorded in exposures
type: string
hashAttribute:
type: string
seed:
type: string
variations:
type: array
items:
type: object
properties:
id:
type: string
key:
type: string
name:
type: string
description:
type: string
config:
description: The ranker's config, as a JSON string
type: string
required:
- id
- key
- name
- config
additionalProperties: false
jsonSchema:
anyOf:
- description: Validation schema for the rankers' configs
type: object
properties:
schemaType:
type: string
enum:
- schema
- simple
schema:
type: string
simple:
type: object
properties:
type:
type: string
enum:
- object
- object[]
- primitive
- primitive[]
fields:
type: array
items:
type: object
properties:
key:
type: string
maxLength: 64
type:
type: string
enum:
- integer
- float
- string
- boolean
required:
type: boolean
default:
type: string
maxLength: 256
description:
type: string
maxLength: 10000
enum:
maxItems: 256
type: array
items:
type: string
maxLength: 256
min:
type: number
max:
type: number
nullable:
type: boolean
jsonSchema:
type: string
required:
- key
- type
- required
- default
- description
- enum
additionalProperties: false
additionalProperties:
type: boolean
invariants:
type: array
items:
type: object
properties:
name:
type: string
maxLength: 128
rule:
type: string
message:
type: string
maxLength: 10000
required:
- name
- rule
- message
additionalProperties: false
required:
- type
- fields
additionalProperties: false
enabled:
type: boolean
date:
type: string
format: date-time
required:
- schemaType
- schema
- simple
- enabled
- date
additionalProperties: false
- type: 'null'
datasource:
type: string
interleavingQueryId:
type: string
userIdType:
type: string
metrics:
type: array
items:
type: object
properties:
id:
type: string
analyses:
minItems: 1
type: array
items:
anyOf:
- type: object
properties:
type:
type: string
const: paired
required:
- type
additionalProperties: false
- type: object
properties:
type:
type: string
const: ownership
attribution:
type: string
enum:
- exposureCount
- engagementSignal
required:
- type
- attribution
additionalProperties: false
required:
- id
- analyses
additionalProperties: false
coverage:
type: number
minimum: 0
maximum: 1
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
environmentSettings:
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
enabled:
type: boolean
required:
- enabled
additionalProperties: false
required:
- id
- dateCreated
- dateUpdated
- name
- owner
- tags
- archived
- status
- key
- trackingKey
- hashAttribute
- seed
- variations
- jsonSchema
- datasource
- interleavingQueryId
- userIdType
- metrics
- environmentSettings
additionalProperties: false
CustomField:
type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
name:
type: string
description:
type: string
placeholder:
type: string
defaultValue:
anyOf:
- type: string
- type: number
- type: boolean
- type: string
format: date-time
- type: string
format: date
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
- type: array
items:
type: string
- type: array
items:
type: number
- type: array
items:
type: boolean
- type: array
items:
type: string
format: date-time
- type: array
items:
type: string
format: date
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
type:
type: string
enum:
- text
- textarea
- markdown
- enum
- multiselect
- url
- number
- boolean
- date
- datetime
values:
type: string
creatable:
type: boolean
required:
type: boolean
creator:
type: string
projects:
type: array
items:
type: string
sections:
type: array
items:
type: string
enum:
- feature
- experiment
- attribute
active:
type: boolean
required:
- id
- dateCreated
- dateUpdated
- name
- type
- required
- sections
additionalProperties: false
MetricGroup:
type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
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
name:
type: string
description:
type: string
maxLength: 10000
tags:
type: array
items:
type: string
projects:
type: array
items:
type: string
metrics:
type: array
items:
type: string
datasource:
type: string
archived:
type: boolean
required:
- id
- dateCreated
- dateUpdated
- owner
- name
- description
- tags
- projects
- metrics
- datasource
- archived
additionalProperties: false
Team:
type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
name:
type: string
createdBy:
type: string
description:
type: string
role:
type: string
limitAccessByEnvironment:
type: boolean
environments:
type: array
items:
type: string
projectRoles:
type: array
items:
type: object
properties:
role:
type: string
limitAccessByEnvironment:
type: boolean
environments:
type: array
items:
type: string
teams:
type: array
items:
type: string
additionalRoles:
type: array
items:
type: object
properties:
role:
type: string
limitAccessByEnvironment:
type: boolean
environments:
type: array
items:
type: string
required:
- role
- limitAccessByEnvironment
- environments
additionalProperties: false
project:
type: string
required:
- role
- limitAccessByEnvironment
- environments
- project
additionalProperties: false
members:
readOnly: true
type: array
items:
type: string
managedByIdp:
type: boolean
managedBy:
anyOf:
- type: object
properties:
type:
type: string
const: vercel
resourceId:
type: string
required:
- type
- resourceId
additionalProperties: false
defaultProject:
type: string
required:
- id
- dateCreated
- dateUpdated
- name
- createdBy
- description
- role
- limitAccessByEnvironment
- environments
- members
- managedByIdp
additionalProperties: false
ExperimentTemplate:
type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
project:
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
templateMetadata:
type: object
properties:
name:
type: string
description:
type: string
maxLength: 10000
required:
- name
additionalProperties: false
type:
type: string
enum:
- standard
hypothesis:
type: string
description:
type: string
maxLength: 10000
tags:
type: array
items:
type: string
customFields:
type: object
propertyNames:
type: string
additionalProperties:
type: string
datasource:
type: string
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
hashAttribute:
type: string
fallbackAttribute:
type: string
disableStickyBucketing:
type: boolean
goalMetrics:
type: array
items:
type: string
secondaryMetrics:
type: array
items:
type: string
guardrailMetrics:
type: array
items:
type: string
activationMetric:
type: string
statsEngine:
type: string
enum:
- bayesian
- frequentist
segment:
type: string
skipPartialData:
type: boolean
targeting:
type: object
properties:
coverage:
type: number
minimum: 0
maximum: 1
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
condition:
type: string
required:
- coverage
- condition
additionalProperties: false
customMetricSlices:
type: array
items:
type: object
properties:
slices:
type: array
items:
type: object
properties:
column:
type: string
levels:
type: array
items:
type: string
required:
- column
- levels
additionalProperties: false
required:
- slices
additionalProperties: false
required:
- id
- dateCreated
- dateUpdated
- owner
- templateMetadata
- type
- datasource
- exposureQuery
- exposureQueryId
- statsEngine
- targeting
additionalProperties: false
AnalyticsExploration:
type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
datasource:
type: string
status:
type: string
enum:
- running
- success
- error
dateStart:
type: string
dateEnd:
type: string
error:
anyOf:
- type: string
- type: 'null'
result:
type: object
properties:
rows:
type: array
items:
type: object
properties:
dimensions:
type: array
items:
anyOf:
- type: string
- type: 'null'
values:
type: array
items:
type: object
properties:
metricId:
type: string
numerator:
anyOf:
- type: number
- type: 'null'
denominator:
anyOf:
- type: number
- type: 'null'
required:
- metricId
- numerator
- denominator
additionalProperties: false
steps:
type: array
items:
type: object
properties:
count:
type: number
timeFromPrevSumHrs:
anyOf:
- type: number
- type: 'null'
timeFromPrevSumSquaresHrs:
anyOf:
- type: number
- type: 'null'
required:
- count
- timeFromPrevSumHrs
- timeFromPrevSumSquaresHrs
additionalProperties: false
journey:
anyOf:
- type: object
properties:
kind:
type: string
const: path
direction:
type: string
enum:
- forward
- backward
levels:
type: array
items:
type: string
count:
type: number
required:
- kind
- direction
- levels
- count
additionalProperties: false
- type: object
properties:
kind:
type: string
const: committed
direction:
type: string
enum:
- forward
- backward
stepIndex:
type: number
value:
type: string
count:
type: number
required:
- kind
- direction
- stepIndex
- value
- count
additionalProperties: false
required:
- dimensions
additionalProperties: false
rawRows:
type: array
items:
type: object
propertyNames:
type: string
additionalProperties: {}
truncated:
type: boolean
required:
- rows
additionalProperties: false
config:
anyOf:
- type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: metric
dataset:
type: object
properties:
type:
type: string
const: metric
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: metric
metricId:
type: string
unit:
anyOf:
- type: string
- type: 'null'
denominatorUnit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- metricId
- unit
- denominatorUnit
additionalProperties: false
required:
- type
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
- type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: fact_table
dataset:
type: object
properties:
type:
type: string
const: fact_table
factTableId:
anyOf:
- type: string
- type: 'null'
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: fact_table
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
required:
- type
- factTableId
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
- type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: data_source
dataset:
type: object
properties:
type:
type: string
const: data_source
table:
type: string
path:
type: string
timestampColumn:
type: string
columnTypes:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- string
- number
- date
- boolean
- other
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: data_source
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
required:
- type
- table
- path
- timestampColumn
- columnTypes
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
- type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: sql
dataset:
type: object
properties:
type:
type: string
const: sql
sql:
type: string
timestampColumn:
anyOf:
- type: string
- type: 'null'
columnTypes:
type: object
propertyNames:
type: string
additionalProperties:
type: string
enum:
- string
- number
- date
- boolean
- other
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: sql
valueType:
type: string
enum:
- unit_count
- count
- sum
valueColumn:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- valueType
- valueColumn
- unit
additionalProperties: false
hiddenColumns:
type: array
items:
type: string
required:
- type
- sql
- timestampColumn
- columnTypes
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
- type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: funnel
dataset:
type: object
properties:
type:
type: string
const: funnel
unit:
anyOf:
- type: string
- type: 'null'
steps:
maxItems: 20
type: array
items:
type: object
properties:
name:
type: string
factTableId:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
optional:
type: boolean
conversionWindow:
anyOf:
- type: object
properties:
unit:
type: string
enum:
- weeks
- days
- hours
- minutes
value:
type: number
exclusiveMinimum: 0
required:
- unit
- value
additionalProperties: false
- type: 'null'
required:
- name
- factTableId
- rowFilters
- optional
additionalProperties: false
concurrencyWindowSeconds:
type: integer
minimum: 0
yAxisScale:
type: string
enum:
- count
- percent
required:
- type
- unit
- steps
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
- type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
- rawTable
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- yesterday
- last7Days
- last30Days
- last90Days
- last12Months
- lastCalendarYear
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
chartSettings:
type: object
properties:
categoryAxisLabel:
type: string
valueAxisLabel:
type: string
additionalProperties: false
type:
type: string
const: journey
dataset:
type: object
properties:
type:
type: string
const: journey
factTableId:
anyOf:
- type: string
- type: 'null'
unit:
anyOf:
- type: string
- type: 'null'
stepColumns:
maxItems: 3
type: array
items:
type: string
stepGroups:
maxItems: 25
type: array
items:
type: object
properties:
column:
type: string
pattern:
type: string
required:
- column
- pattern
additionalProperties: false
anchorStepValues:
anyOf:
- type: array
items:
type: string
- type: 'null'
direction:
type: string
enum:
- forward
- backward
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
path:
maxItems: 15
type: array
items:
type: object
properties:
value:
type: string
required:
- value
additionalProperties: false
lookaheadDepth:
type: integer
minimum: 1
maximum: 4
optionsPerStep:
type: array
items:
type: integer
minimum: 2
maximum: 50
heightScale:
type: string
enum:
- relative
- absolute
required:
- type
- factTableId
- unit
- stepColumns
- anchorStepValues
- direction
- rowFilters
- path
- lookaheadDepth
- optionsPerStep
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
required:
- id
- dateCreated
- dateUpdated
- datasource
- status
- dateStart
- dateEnd
- result
- config
additionalProperties: false
RampScheduleTemplate:
type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
name:
type: string
steps:
type: array
items:
type: object
properties:
interval:
description: >-
Hold duration in seconds before this step's gates are
evaluated. null = no time gate (advance as soon as
holdConditions clear).
anyOf:
- type: number
exclusiveMinimum: 0
- type: 'null'
approvalNotes:
anyOf:
- type: string
- type: 'null'
monitored:
description: >-
When true, this step runs A/B traffic analysis while active.
Treatment = [0, coverage), control = [0.5, 0.5+coverage). Arms
are equal-sized and non-adjacent: step-ups only add users,
never reassign existing ones. The UI caps monitored-step
coverage at 0.5 so control end never exceeds 1.0. The SDK uses
explicit hash ranges on the experiment rule to prevent
bucketing shifts across monitored/unmonitored transitions.
type: boolean
holdConditions:
type: object
properties:
minSampleSize:
type: integer
exclusiveMinimum: 0
requiresApproval:
type: boolean
additionalProperties: false
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'
enabled:
anyOf:
- type: boolean
- type: 'null'
force:
description: >-
Ignored: templates never carry force values.
Accepted so a schedule's steps can be copied into a
template.
required:
- ruleId
additionalProperties: false
required:
- targetType
- targetId
- patch
additionalProperties: false
required:
- interval
- actions
additionalProperties: false
endPatch:
type: object
properties:
coverage:
type: number
minimum: 0
maximum: 1
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
allEnvironments:
type: boolean
environments:
type: array
items:
type: string
additionalProperties: false
official:
type: boolean
monitoringConfig:
anyOf:
- 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
- type: 'null'
lockdownConfig:
anyOf:
- type: object
properties:
mode:
type: string
enum:
- none
- locked
required:
- mode
additionalProperties: false
- type: 'null'
order:
description: >-
Manual display order within the org (read-only; managed via the
app).
type: number
required:
- id
- dateCreated
- dateUpdated
- name
- steps
- order
additionalProperties: false
Learning:
type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
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
authors:
type: array
items:
type: string
title:
type: string
text:
type: string
tags:
type: array
items:
type: string
supportingExperimentIds:
type: array
items:
type: string
contradictingExperimentIds:
type: array
items:
type: string
projects:
type: array
items:
type: string
status:
type: string
source:
type: string
enum:
- ai
- manual
- api
required:
- id
- dateCreated
- dateUpdated
- owner
- authors
- title
- text
- tags
- supportingExperimentIds
- contradictingExperimentIds
- projects
- status
- source
additionalProperties: false
Holdout:
type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
name:
type: string
description:
type: string
maxLength: 10000
projects:
description: >-
Project IDs this Holdout applies to. An empty array means All
Projects.
type: array
items:
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
tags:
type: array
items:
type: string
archived:
type: boolean
stage:
description: >-
Lifecycle stage of the Holdout. Use the start, start-analysis, and
stop endpoints to move through the lifecycle.
type: string
enum:
- draft
- running
- analysis-period
- stopped
trackingKey:
type: string
experimentId:
description: >-
ID of the companion experiment that stores this Holdout's analysis.
Use it with the experiment results endpoints (e.g. GET
/experiments/{experimentId}/results). Pass phase=0 for results
across the whole Holdout period, or phase=1 for results limited to
the analysis period.
type: string
skipAsDefaultHoldout:
description: >-
When true, this Holdout is not selected automatically when creating
Feature Flags or experiments in Projects assigned to the Holdout.
type: boolean
holdoutSize:
description: >-
Proportion of traffic placed in the holdout group (e.g. 0.05 for
5%). An equally sized comparison group is sampled from the remaining
traffic for measurement, so 2× this value enters the holdout
experiment in total. Must be greater than 0 and at most 0.5.
type: number
exclusiveMinimum: 0
maximum: 0.5
hashAttribute:
description: Attribute used to assign users to the Holdout.
type: string
targetingCondition:
description: Targeting condition as a JSON string.
type: string
savedGroupTargeting:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
datasourceId:
type: string
assignmentQuery:
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
assignmentQueryId:
description: 'Deprecated: use `assignmentQuery`.'
deprecated: true
type: string
goalMetrics:
type: array
items:
type: string
secondaryMetrics:
type: array
items:
type: string
statsEngine:
description: Statistics engine used to analyze this Holdout.
type: string
enum:
- bayesian
- frequentist
variations:
type: array
items:
type: object
properties:
variationId:
type: string
key:
type: string
name:
type: string
description:
type: string
maxLength: 10000
required:
- variationId
- key
- name
additionalProperties: false
environments:
description: >-
Per-environment state, keyed by environment ID. Environments not
present are disabled.
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
enabled:
description: Whether the Holdout is active in this environment.
type: boolean
required:
- enabled
additionalProperties: false
linkedFeatures:
description: >-
Feature Flags held out by this Holdout. Manage these through the
Feature Flag endpoints.
type: array
items:
type: object
properties:
id:
type: string
dateAdded:
type: string
format: date-time
required:
- id
- dateAdded
additionalProperties: false
linkedExperiments:
description: >-
Experiments held out by this Holdout. Manage these through the
experiment endpoints.
type: array
items:
type: object
properties:
id:
type: string
dateAdded:
type: string
format: date-time
required:
- id
- dateAdded
additionalProperties: false
dateStarted:
type: string
format: date-time
analysisStartDate:
description: When the Holdout entered its analysis period.
type: string
format: date-time
dateStopped:
type: string
format: date-time
statusUpdateSchedule:
anyOf:
- description: >-
Automatic stage transitions for the Holdout. Dates must be
consecutive: `startAt` before `startAnalysisPeriodAt` before
`stopAt`. Send `null` to delete the schedule.
type: object
properties:
startAt:
description: >-
ISO datetime to move the Holdout from `draft` to `running`.
Must be in the future while the Holdout is still a draft.
type: string
format: date-time
startAnalysisPeriodAt:
description: >-
ISO datetime to move the Holdout from `running` to
`analysis-period`. Requires `startAt` while the Holdout is
still a draft.
type: string
format: date-time
stopAt:
description: >-
ISO datetime to stop the Holdout. Requires
`startAnalysisPeriodAt` unless the analysis period has
already begun.
type: string
format: date-time
additionalProperties: false
- type: 'null'
nextScheduledStatusUpdate:
anyOf:
- description: The next stage transition that will run automatically.
type: object
properties:
type:
type: string
enum:
- start
- startAnalysisPeriod
- stop
date:
type: string
format: date-time
required:
- type
- date
additionalProperties: false
- type: 'null'
required:
- id
- dateCreated
- dateUpdated
- name
- description
- projects
- owner
- tags
- archived
- stage
- trackingKey
- experimentId
- skipAsDefaultHoldout
- holdoutSize
- hashAttribute
- targetingCondition
- datasourceId
- assignmentQuery
- assignmentQueryId
- goalMetrics
- secondaryMetrics
- variations
- environments
- linkedFeatures
- linkedExperiments
additionalProperties: false
AutoRun:
type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
source:
type: string
enum:
- cli-wizard
- skill
- eppo-import
agent:
anyOf:
- type: string
- type: 'null'
createdBy:
description: Id of the user who ran the wizard
anyOf:
- type: string
- type: 'null'
metadata:
description: >-
What the wizard learned about the environment it ran in — language,
packageManager, framework, versions. Open by design; do not rely on
any single key being present
type: object
propertyNames:
type: string
maxLength: 60
additionalProperties:
anyOf:
- type: string
maxLength: 500
- type: number
- type: boolean
- type: 'null'
artifacts:
type: array
items:
type: object
properties:
kind:
type: string
enum:
- sdk-connection
- feature
- experiment
- attribute
- metric
- fact-table
- saved-group
- environment
- tag
id:
type: string
label:
type: string
by:
type: string
enum:
- developer
- growthbook
detail:
anyOf:
- type: string
- type: 'null'
externalId:
description: Id in the system this was imported from, when it was imported
anyOf:
- type: string
- type: 'null'
action:
description: What the run did to this object
type: string
enum:
- created
- updated
- existing
- deleted
- failed
dateCreated:
type: string
format: date-time
required:
- kind
- id
- label
- by
- detail
- dateCreated
additionalProperties: false
checks:
type: array
items:
type: object
properties:
name:
type: string
maxLength: 100
ok:
type: boolean
required:
type: boolean
required:
- name
- ok
- required
additionalProperties: false
outcome:
anyOf:
- type: string
enum:
- completed
- partial
- failed
- type: 'null'
failureReason:
anyOf:
- type: string
- type: 'null'
dateCompleted:
anyOf:
- type: string
format: date-time
- type: 'null'
url:
description: >-
Absolute URL of the run's page in the app. Built server-side so
callers never guess the app origin
type: string
required:
- id
- dateCreated
- dateUpdated
- source
- agent
- createdBy
- metadata
- artifacts
- checks
- outcome
- failureReason
- dateCompleted
- url
additionalProperties: false
Population:
type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
projects:
type: array
items:
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
name:
type: string
description:
type: string
datasource:
type: string
userIdTypes:
type: array
items:
type: string
steps:
type: array
items:
type: object
properties:
source:
anyOf:
- type: object
properties:
type:
type: string
const: factTable
factTableId:
type: string
required:
- type
- factTableId
additionalProperties: false
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- between
- not_between
- in
- not_in
- contains
- not_contains
- matches_pattern
- not_matches_pattern
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
aggregateFilter:
description: >-
Conditions on each unit's total within the queried date range,
such as ">=3" or ">=3,<10". Requires aggregateFilterColumn
type: string
aggregateFilterColumn:
description: >-
Numeric column to total, or "$$count" to count rows. Requires
aggregateFilter
type: string
required:
- source
- rowFilters
additionalProperties: false
required:
- id
- dateCreated
- dateUpdated
- projects
- owner
- name
- description
- datasource
- userIdTypes
- steps
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.checklist
- 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
ExperimentSnapshot:
type: object
properties:
id:
type: string
experiment:
type: string
status:
type: string
required:
- id
- experiment
- status
additionalProperties: false
VisualChange:
type: object
properties:
id:
type: string
description:
type: string
css:
type: string
js:
type: string
variation:
type: string
domMutations:
type: array
items:
type: object
properties:
selector:
type: string
action:
type: string
enum:
- append
- set
- remove
attribute:
type: string
value:
type: string
parentSelector:
type: string
insertBeforeSelector:
type: string
required:
- selector
- action
- attribute
additionalProperties: false
required:
- variation
additionalProperties: false
FeatureDefinition:
type: object
properties:
defaultValue:
anyOf:
- type: string
- type: number
- type: array
items: {}
- type: object
propertyNames:
type: string
additionalProperties: {}
- type: 'null'
rules:
type: array
items:
type: object
properties:
force:
anyOf:
- type: string
- type: number
- type: array
items: {}
- type: object
propertyNames:
type: string
additionalProperties: {}
- type: 'null'
weights:
type: array
items:
type: number
variations:
type: array
items:
anyOf:
- type: string
- type: number
- type: array
items: {}
- type: object
propertyNames:
type: string
additionalProperties: {}
- type: 'null'
hashAttribute:
type: string
namespace:
minItems: 3
maxItems: 3
type: array
items:
anyOf:
- type: number
- type: string
key:
type: string
coverage:
type: number
condition:
type: object
propertyNames:
type: string
additionalProperties: {}
additionalProperties: false
required:
- defaultValue
additionalProperties: false
ConfigReferences:
type: object
properties:
features:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
project:
type: string
required:
- id
additionalProperties: false
constants:
type: array
items:
type: object
properties:
id:
type: string
key:
type: string
name:
type: string
project:
type: string
isConfig:
type: boolean
required:
- id
- key
- name
additionalProperties: false
required:
- features
- constants
additionalProperties: false
ConfigKeyUsage:
type: object
properties:
familyKeys:
type: array
items:
type: string
implementations:
type: array
items:
type: object
properties:
featureId:
type: string
project:
type: string
location:
type: string
enum:
- defaultValue
- rule
ruleType:
type: string
ruleId:
type: string
experimentId:
type: string
experimentName:
type: string
experimentStatus:
type: string
variationId:
type: string
configKey:
type: string
relation:
type: string
enum:
- self
- ancestor
- descendant
- other
keys:
type: array
items:
type: string
state:
type: string
enum:
- live
- draft
revisionVersion:
type: number
required:
- featureId
- location
- configKey
- keys
- state
additionalProperties: false
required:
- familyKeys
- implementations
additionalProperties: false
ConfigLineage:
type: object
properties:
root:
description: The key of the family root (the topmost ancestor).
type: string
target:
description: The requested config's key.
type: string
ancestors:
description: >-
The target's ancestor keys, root-first, ending at its immediate
parent.
type: array
items:
type: string
descendants:
description: Keys of every config that descends from the target.
type: array
items:
type: string
nodes:
description: >-
Every config in the family (root plus all descendants),
breadth-first.
type: array
items:
type: object
properties:
key:
type: string
name:
type: string
parent:
description: >-
The lineage parent's key (tree spine), or null for the family
root.
anyOf:
- type: string
- type: 'null'
extends:
description: >-
Additional composition bases (mixin config keys) layered on
top of `parent`. The tree shape follows `parent`/`depth`;
these express composition beyond the parent/child spine.
type: array
items:
type: string
project:
type: string
archived:
type: boolean
depth:
description: >-
Distance from the family root along the `parent` spine (root
is 0).
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
isTarget:
description: True for the requested config.
type: boolean
incompatibleFields:
description: >-
Own value keys whose value no longer conforms to the effective
(inherited) field type and must be fixed. Empty when all
conform.
type: array
items:
type: string
orphanedFields:
description: >-
Own value keys the effective schema no longer declares (e.g.
an ancestor removed the field). They still resolve and are
served, but nothing validates them and validation rules read
them as null; a non-extensible family rejects them on the next
changing publish.
type: array
items:
type: string
required:
- key
- name
- parent
- archived
- depth
- isTarget
additionalProperties: false
required:
- root
- target
- ancestors
- descendants
- nodes
additionalProperties: false
ConfigSchemaExport:
type: object
properties:
schema:
description: >-
The config's schema in the requested format: a JSON Schema document
(`{ type: "json-schema", value }`) or rendered TypeScript source (`{
type: "typescript", value }`).
$ref: '#/components/schemas/ConfigSchemaSource'
effective:
description: >-
True when the schema includes inherited fields accumulated across
the lineage; false when it is only this config's own fields.
type: boolean
additionalProperties:
description: Whether the config family permits extra keys.
type: boolean
required:
- schema
- effective
- additionalProperties
additionalProperties: false
$defs:
ConfigSchemaSource:
id: 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
ConfigSchemaVerify:
type: object
properties:
inSync:
description: >-
True when the supplied schema is canonically identical to the
config's stored schema.
type: boolean
fingerprint:
description: Canonical fingerprint of the config's stored schema.
type: string
incomingFingerprint:
description: Canonical fingerprint of the supplied schema.
type: string
drift:
description: Present only when `inSync` is false.
type: object
properties:
contract:
description: >-
Changes that alter what validates
(type/enum/required/nullable/bounds/structure, or an
added/removed field).
type: array
items:
type: object
properties:
key:
type: string
change:
type: string
enum:
- added
- removed
- changed
required:
- key
- change
additionalProperties: false
docs:
description: Description-only changes (no effect on validation).
type: array
items:
type: object
properties:
key:
type: string
change:
type: string
enum:
- added
- removed
- changed
required:
- key
- change
additionalProperties: false
required:
- contract
- docs
additionalProperties: false
ancestorOwnedFields:
description: >-
Supplied fields an ancestor config already owns ("base wins").
Subtract these from `drift.contract` adds when round-tripping a full
effective schema.
type: array
items:
type: object
properties:
key:
type: string
ownedBy:
description: Key of the ancestor config that owns the field.
type: string
identical:
description: >-
True when the supplied definition matches the ancestor's
contract — a save would strip it harmlessly (with a warning).
False means a save would be rejected.
type: boolean
required:
- key
- ownedBy
- identical
additionalProperties: false
warnings:
type: array
items:
$ref: '#/components/schemas/ConfigSchemaWarning'
required:
- inSync
- fingerprint
- incomingFingerprint
additionalProperties: false
$defs:
ConfigSchemaWarning:
id: 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
SavedGroupReferences:
type: object
properties:
features:
type: array
items:
$ref: '#/components/schemas/SavedGroupReferenceResource'
experiments:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
project:
type: string
projects:
type: array
items:
type: string
required:
- id
additionalProperties: false
contextualBandits:
type: array
items:
$ref: '#/components/schemas/SavedGroupReferenceResource'
interleavings:
type: array
items:
$ref: '#/components/schemas/SavedGroupReferenceResource'
savedGroups:
type: array
items:
type: object
properties:
id:
type: string
groupName:
type: string
projects:
type: array
items:
type: string
required:
- id
additionalProperties: false
required:
- features
- experiments
- contextualBandits
- interleavings
- savedGroups
additionalProperties: false
$defs:
SavedGroupReferenceResource:
id: SavedGroupReferenceResource
type: object
properties:
id:
type: string
name:
type: string
project:
type: string
required:
- id
additionalProperties: false
ConstantReferences:
type: object
properties:
features:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
project:
type: string
required:
- id
additionalProperties: false
constants:
type: array
items:
type: object
properties:
id:
type: string
key:
type: string
name:
type: string
project:
type: string
required:
- id
- key
- name
additionalProperties: false
required:
- features
- constants
additionalProperties: false
ApiErrorConflictDetails:
type: object
properties:
conflicts:
type: array
items: {}
required:
- conflicts
additionalProperties: false
ApiErrorChecklistIncompleteDetails:
type: object
properties:
remainingChecklistItems:
type: array
items:
type: object
properties:
key:
type: string
required:
type: boolean
status:
type: string
enum:
- complete
- incomplete
manual:
type: boolean
reason:
type: string
hardBlock:
type: boolean
required:
- key
- required
- status
- manual
- reason
additionalProperties: false
required:
- remainingChecklistItems
additionalProperties: false
ApiErrorPendingDraftPublishFailedDetails:
type: object
properties:
failedFeatureDrafts:
type: array
items:
type: object
properties:
featureId:
type: string
revisionVersion:
type: number
reason:
type: string
enum:
- merge-conflict
- needs-rebase
- needs-approval
- publish-error
required:
- featureId
- revisionVersion
- reason
additionalProperties: false
required:
- failedFeatureDrafts
additionalProperties: false
ApiErrorInvalidStatusDetails:
type: object
properties:
currentStatus:
type: string
expectedStatuses:
type: array
items:
type: string
required:
- currentStatus
- expectedStatuses
additionalProperties: false
ApiErrorRequiresFullRefreshDetails:
type: object
properties:
reason:
type: string
required:
- reason
additionalProperties: false
ApiErrorDimensionAlreadyUpToDateDetails:
type: object
properties:
overallResultsAsOf:
type: string
required:
- overallResultsAsOf
additionalProperties: false
ApiErrorInvalidTrackingKeyDetails:
type: object
properties:
pattern:
type: string
example:
type: string
required:
- pattern
- example
additionalProperties: false
ApiErrorChangesConflictDetails:
type: object
properties:
fields:
type: array
items:
type: string
featureIds:
type: array
items:
type: string
urlRedirectIds:
type: array
items:
type: string
visualChangesetIds:
type: array
items:
type: string
required:
- fields
- featureIds
- urlRedirectIds
- visualChangesetIds
additionalProperties: false
ApiErrorUnscopedRuleDetails:
type: object
properties:
ruleIds:
type: array
items:
type: string
required:
- ruleIds
additionalProperties: false
ApiErrorCustomHookErrorDetails:
type: object
properties:
hooks:
type: array
items:
type: object
properties:
hookName:
type: string
rejected:
type: boolean
message:
type: string
stack:
type: string
log:
type: string
required:
- hookName
- rejected
- message
additionalProperties: false
required:
- hooks
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
- skipChecklist
required:
- type
- outcome
- via
additionalProperties: false
features:
description: >-
Map of feature ID to stale status. Only requested features that were
found and readable are included.
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
featureId:
description: The feature key
type: string
isStale:
description: >-
Whether the feature is considered stale overall (all enabled
environments are stale). Always false when neverStale is true.
type: boolean
staleReason:
description: >
Reason for the feature's stale or non-stale status. `never-stale`
when stale detection is disabled. Non-stale reasons:
`recently-updated`, `active-draft`, `has-dependents`,
`temp-rollout` (a rule serves a recently stopped experiment's
released variation). Stale reasons: `no-rules`, `rules-one-sided`,
`abandoned-draft`, `toggled-off`, `old-temp-rollout` (the
environment only serves the released variation of an experiment
stopped more than 30 days ago). Null when non-stale with no single
cause (see staleByEnv).
anyOf:
- type: string
enum:
- never-stale
- recently-updated
- active-draft
- has-dependents
- no-rules
- rules-one-sided
- abandoned-draft
- toggled-off
- active-experiment
- temp-rollout
- old-temp-rollout
- has-rules
- type: 'null'
neverStale:
description: >-
When true the feature is permanently excluded from stale
detection.
type: boolean
staleByEnv:
description: >-
Per-environment staleness breakdown, keyed by environment ID.
Present when environments exist and neverStale is false.
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
isStale:
description: Whether this environment is stale
type: boolean
reason:
description: Reason for the stale status in this environment
anyOf:
- type: string
enum:
- no-rules
- rules-one-sided
- abandoned-draft
- toggled-off
- active-experiment
- temp-rollout
- old-temp-rollout
- has-rules
- recently-updated
- active-draft
- has-dependents
- type: 'null'
evaluatesTo:
description: >
The deterministic value this feature evaluates to in this
environment. Uses the same raw string encoding as
`feature.defaultValue`. Only present when the value is
deterministic or the environment is toggled off.
type: string
tempRollout:
description: >
Present when a reachable rule still serves a stopped
experiment's released variation (a temporary rollout that
can be cleaned up). `old-temp-rollout` once the experiment
has been stopped for more than 30 days.
type: string
enum:
- temp-rollout
- old-temp-rollout
required:
- isStale
- reason
additionalProperties: false
required:
- featureId
- isStale
- staleReason
- neverStale
additionalProperties: false
conflicts:
type: object
properties:
name:
type: string
key:
type: string
resolved:
type: boolean
base:
type: string
live:
type: string
revision:
type: string
required:
- name
- key
- resolved
- base
- live
- revision
additionalProperties: false
result:
type: object
properties:
defaultValue:
type: string
rules:
type: array
items:
anyOf:
- type: object
properties:
description:
type: string
maxLength: 10000
condition:
type: string
id:
type: string
allEnvironments:
type: boolean
environments:
type: array
items:
type: string
allProjects:
type: boolean
projects:
type: array
items:
type: string
enabled:
type: boolean
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
anyOf:
- type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleType:
type: string
enum:
- none
- schedule
- ramp
type:
type: string
const: force
value:
type: string
sparse:
type: boolean
required:
- description
- id
- allEnvironments
- type
- value
additionalProperties: false
- type: object
properties:
description:
type: string
maxLength: 10000
condition:
type: string
id:
type: string
allEnvironments:
type: boolean
environments:
type: array
items:
type: string
allProjects:
type: boolean
projects:
type: array
items:
type: string
enabled:
type: boolean
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
anyOf:
- type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleType:
type: string
enum:
- none
- schedule
- ramp
type:
type: string
const: rollout
value:
type: string
sparse:
type: boolean
coverage:
type: number
hashAttribute:
type: string
fallbackAttribute:
type: string
seed:
type: string
hashVersion:
anyOf:
- type: number
const: 1
- type: number
const: 2
required:
- description
- id
- allEnvironments
- type
- value
- coverage
- hashAttribute
additionalProperties: false
- type: object
properties:
description:
type: string
maxLength: 10000
condition:
type: string
id:
type: string
allEnvironments:
type: boolean
environments:
type: array
items:
type: string
allProjects:
type: boolean
projects:
type: array
items:
type: string
enabled:
type: boolean
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
anyOf:
- type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleType:
type: string
enum:
- none
- schedule
- ramp
type:
type: string
const: experiment
experimentType:
type: string
enum:
- standard
- multi-armed-bandit
hypothesis:
type: string
trackingKey:
type: string
hashAttribute:
type: string
fallbackAttribute:
type: string
hashVersion:
type: number
disableStickyBucketing:
type: boolean
bucketVersion:
type: number
minBucketVersion:
type: number
namespace:
anyOf:
- type: object
properties:
enabled:
type: boolean
name:
type: string
range:
type: array
prefixItems:
- type: number
- type: number
format:
type: string
const: legacy
required:
- enabled
- name
- range
additionalProperties: false
- type: object
properties:
enabled:
type: boolean
name:
type: string
ranges:
type: array
items:
type: array
prefixItems:
- type: number
- type: number
hashAttribute:
type: string
hashVersion:
type: number
format:
type: string
const: multiRange
required:
- enabled
- name
- ranges
- format
additionalProperties: false
coverage:
type: number
datasource:
type: string
exposureQueryId:
type: string
goalMetrics:
type: array
items:
type: string
secondaryMetrics:
type: array
items:
type: string
guardrailMetrics:
type: array
items:
type: string
activationMetric:
type: string
segment:
type: string
skipPartialData:
type: boolean
values:
type: array
items:
type: object
properties:
value:
type: string
weight:
type: number
name:
type: string
required:
- value
- weight
additionalProperties: false
regressionAdjustmentEnabled:
type: boolean
sequentialTestingEnabled:
type: boolean
sequentialTestingTuningParameter:
type: number
statsEngine:
type: string
enum:
- bayesian
- frequentist
banditStage:
type: string
enum:
- explore
- exploit
- paused
banditStageDateStarted: {}
banditScheduleValue:
type: number
banditScheduleUnit:
type: string
enum:
- hours
- days
banditBurnInValue:
type: number
banditBurnInUnit:
type: string
enum:
- hours
- days
banditConversionWindowValue:
anyOf:
- type: number
- type: 'null'
banditConversionWindowUnit:
anyOf:
- type: string
enum:
- hours
- days
- type: 'null'
templateId:
type: string
customFields:
type: object
propertyNames:
type: string
additionalProperties: {}
required:
- description
- id
- allEnvironments
- type
- trackingKey
- hashAttribute
- values
additionalProperties: false
- type: object
properties:
description:
type: string
maxLength: 10000
condition:
type: string
id:
type: string
allEnvironments:
type: boolean
environments:
type: array
items:
type: string
allProjects:
type: boolean
projects:
type: array
items:
type: string
enabled:
type: boolean
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
anyOf:
- type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleType:
type: string
enum:
- none
- schedule
- ramp
type:
type: string
const: experiment-ref
experimentId:
type: string
variations:
type: array
items:
type: object
properties:
variationId:
type: string
value:
type: string
required:
- variationId
- value
additionalProperties: false
sparse:
type: boolean
required:
- description
- id
- allEnvironments
- type
- experimentId
- variations
additionalProperties: false
- type: object
properties:
description:
type: string
maxLength: 10000
condition:
type: string
id:
type: string
allEnvironments:
type: boolean
environments:
type: array
items:
type: string
allProjects:
type: boolean
projects:
type: array
items:
type: string
enabled:
type: boolean
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
anyOf:
- type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleType:
type: string
enum:
- none
- schedule
- ramp
type:
type: string
const: contextual-bandit-ref
contextualBanditId:
type: string
variations:
type: array
items:
type: object
properties:
variationId:
type: string
value:
type: string
required:
- variationId
- value
additionalProperties: false
required:
- description
- id
- allEnvironments
- type
- contextualBanditId
- variations
additionalProperties: false
- type: object
properties:
description:
type: string
maxLength: 10000
condition:
type: string
id:
type: string
allEnvironments:
type: boolean
environments:
type: array
items:
type: string
allProjects:
type: boolean
projects:
type: array
items:
type: string
enabled:
type: boolean
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
anyOf:
- type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleType:
type: string
enum:
- none
- schedule
- ramp
type:
type: string
const: safe-rollout
controlValue:
type: string
variationValue:
type: string
safeRolloutId:
type: string
status:
default: running
type: string
enum:
- running
- rolled-back
- released
- stopped
hashAttribute:
type: string
seed:
type: string
trackingKey:
type: string
required:
- description
- id
- allEnvironments
- type
- controlValue
- variationValue
- safeRolloutId
- status
- hashAttribute
- seed
- trackingKey
additionalProperties: false
environmentsEnabled:
type: object
propertyNames:
type: string
additionalProperties:
type: boolean
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
archived:
type: boolean
metadata:
type: object
properties:
releaseType:
type: string
riskLevel:
type: string
additionalProperties: {}
holdout:
anyOf:
- type: object
properties:
id:
type: string
value:
type: string
required:
- id
- value
additionalProperties: false
- type: 'null'
additionalProperties: false
log:
type: object
properties:
id:
description: >-
Log entry ID. Use a `Comment` entry's id with the PUT/DELETE log
endpoints to edit or delete an owned comment. Absent on legacy
entries stored inline on the revision.
type: string
action:
description: >-
Entry type — content edits (e.g. "add rule", "edit defaultValue",
"rebase"), review lifecycle events ("Review Requested", "Approved",
"Requested Changes"), comments ("Comment"), or other audit events.
type: string
subject:
type: string
value:
description: JSON-encoded payload for the entry
type: string
timestamp:
format: date-time
type: string
user:
anyOf:
- title: Event User
$ref: '#/components/schemas/EventUser'
- type: 'null'
required:
- action
- subject
- value
- timestamp
- user
additionalProperties: false
checklistItems:
type: object
properties:
key:
type: string
required:
type: boolean
status:
type: string
enum:
- complete
- incomplete
manual:
type: boolean
reason:
type: string
hardBlock:
description: >-
When true, this item cannot be bypassed with `skipChecklist` — the
experiment cannot be started until it is resolved.
type: boolean
featureId:
description: The linked Feature Flag the item is about.
type: string
required:
- key
- required
- status
- manual
- reason
additionalProperties: false
gates:
type: object
properties:
key:
description: >-
The checklist item, or `rampLocked:` for a linked Feature
Flag a ramp locks.
type: string
type:
description: >-
Gate kind: "checklist-item", "approval-required", "merge-conflict",
"unrelated-draft-changes", "permission-denied" or "ramp-locked".
type: string
featureId:
description: The linked Feature Flag whose authority decides this gate.
type: string
severity:
type: string
enum:
- blocker
- warning
messages:
type: array
items:
type: string
override:
description: >-
Request flag that gets past this gate on retry, if any
(`skipChecklist`).
anyOf:
- type: string
- type: 'null'
requiresPermission:
description: >-
Permission on the linked Feature Flag's Project that bypasses this
gate.
anyOf:
- type: string
- type: 'null'
resolution:
description: A route that resolves the gate.
anyOf:
- type: object
properties:
action:
type: string
method:
type: string
path:
type: string
required:
- action
- method
- path
additionalProperties: false
- type: 'null'
required:
- key
- type
- severity
- messages
- override
- requiresPermission
- resolution
additionalProperties: false
publishedFeatureDrafts:
type: object
properties:
featureId:
type: string
revisionVersion:
type: number
required:
- featureId
- revisionVersion
additionalProperties: false
snapshot:
type: object
properties:
id:
type: string
experiment:
type: string
status:
type: string
required:
- id
- experiment
- status
additionalProperties: false
screenshot:
type: object
properties:
path:
description: URL or path to the uploaded screenshot
type: string
description:
description: Description of the screenshot
type: string
required:
- path
- description
additionalProperties: false
experiments:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
additionalProperties: false
currentLeafWeights:
type: object
properties:
leafId:
type: integer
condition:
type: object
propertyNames:
type: string
additionalProperties: {}
weights:
type: array
items:
type: object
properties:
variationId:
type: string
weight:
type: number
required:
- variationId
- weight
additionalProperties: false
required:
- leafId
- condition
- weights
additionalProperties: false
snapshots:
type: object
properties:
id:
type: string
contextualBandit:
type: string
status:
type: string
enum:
- pending
- running
- success
- error
- partial
weightsWereUpdated:
type: boolean
contextualBanditEventId:
anyOf:
- type: string
- type: 'null'
error:
type: string
dateCreated:
type: string
required:
- id
- contextualBandit
- status
- dateCreated
additionalProperties: false
events:
type: object
properties:
id:
type: string
contextualBandit:
type: string
snapshotId:
type: string
weightsWereUpdated:
type: boolean
degreesOfFreedom:
type: integer
minimum: 0
dateCreated:
type: string
required:
- id
- contextualBandit
- snapshotId
- weightsWereUpdated
- dateCreated
additionalProperties: false
experimentResults:
type: object
properties:
experimentId:
type: string
experimentName:
type: string
status:
type: string
result:
description: Result of the experiment, set when stopped
type: string
date:
type: string
datasourceId:
type: string
variations:
type: array
items:
type: object
properties:
variationId:
type: string
variationName:
type: string
users:
type: number
value:
type: number
mean:
type: number
lift:
description: Relative uplift mean for this variation, if available
type: number
effectStandardError:
description: Standard error of `lift`, if available
type: number
ci:
description: Confidence interval [lower, upper]
type: array
prefixItems:
- type: number
- type: number
pValue:
type: number
chanceToWin:
type: number
required:
- variationId
- variationName
additionalProperties: false
required:
- experimentId
- experimentName
- status
- date
- datasourceId
- variations
additionalProperties: false
tables:
type: object
properties:
database:
type: string
schema:
type: string
table:
type: string
columnCount:
type: number
required:
- database
- schema
- table
- columnCount
additionalProperties: false
savedGroups:
type: object
properties:
id:
type: string
groupName:
type: string
projects:
type: array
items:
type: string
required:
- id
additionalProperties: false
constants:
type: object
properties:
id:
type: string
key:
type: string
name:
type: string
project:
type: string
required:
- id
- key
- name
additionalProperties: false
implementations:
type: object
properties:
featureId:
type: string
project:
type: string
location:
type: string
enum:
- defaultValue
- rule
ruleType:
type: string
ruleId:
type: string
experimentId:
type: string
experimentName:
type: string
experimentStatus:
type: string
variationId:
type: string
configKey:
type: string
relation:
type: string
enum:
- self
- ancestor
- descendant
- other
keys:
type: array
items:
type: string
state:
type: string
enum:
- live
- draft
revisionVersion:
type: number
required:
- featureId
- location
- configKey
- keys
- state
additionalProperties: false
nodes:
type: object
properties:
key:
type: string
name:
type: string
parent:
description: The lineage parent's key (tree spine), or null for the family root.
anyOf:
- type: string
- type: 'null'
extends:
description: >-
Additional composition bases (mixin config keys) layered on top of
`parent`. The tree shape follows `parent`/`depth`; these express
composition beyond the parent/child spine.
type: array
items:
type: string
project:
type: string
archived:
type: boolean
depth:
description: Distance from the family root along the `parent` spine (root is 0).
type: integer
isTarget:
description: True for the requested config.
type: boolean
incompatibleFields:
description: >-
Own value keys whose value no longer conforms to the effective
(inherited) field type and must be fixed. Empty when all conform.
type: array
items:
type: string
orphanedFields:
description: >-
Own value keys the effective schema no longer declares (e.g. an
ancestor removed the field). They still resolve and are served, but
nothing validates them and validation rules read them as null; a
non-extensible family rejects them on the next changing publish.
type: array
items:
type: string
required:
- key
- name
- parent
- archived
- depth
- isTarget
additionalProperties: false
drift:
description: Present only when `inSync` is false.
type: object
properties:
contract:
description: >-
Changes that alter what validates
(type/enum/required/nullable/bounds/structure, or an added/removed
field).
type: array
items:
type: object
properties:
key:
type: string
change:
type: string
enum:
- added
- removed
- changed
required:
- key
- change
additionalProperties: false
docs:
description: Description-only changes (no effect on validation).
type: array
items:
type: object
properties:
key:
type: string
change:
type: string
enum:
- added
- removed
- changed
required:
- key
- change
additionalProperties: false
required:
- contract
- docs
additionalProperties: false
ancestorOwnedFields:
type: object
properties:
key:
type: string
ownedBy:
description: Key of the ancestor config that owns the field.
type: string
identical:
description: >-
True when the supplied definition matches the ancestor's contract —
a save would strip it harmlessly (with a warning). False means a
save would be rejected.
type: boolean
required:
- key
- ownedBy
- identical
additionalProperties: false
results:
type: object
properties:
entityType:
type: string
enum:
- feature
- saved-group
- config
- constant
id:
description: The identifier used in the request.
type: string
version:
type: integer
revisionId:
description: The revision's id (`rev_…` or `frev_…`).
type: string
status:
type: string
enum:
- published
- would-publish
required:
- entityType
- id
- version
- revisionId
- status
additionalProperties: false
suppressed:
description: >-
Outcomes the previous state produced too, which Incremental Changes Only
would hide on a real save
type: object
properties:
error:
type: string
warnings:
type: array
items:
type: string
additionalProperties: false
versions:
type: object
properties:
auditId:
description: Identifier for this version, used to revert to it
type: string
event:
description: The audit event that produced this version (create/update)
type: string
dateCreated:
format: date-time
type: string
userName:
type: string
userEmail:
type: string
customHook:
description: The hook's full state at this version
$ref: '#/components/schemas/CustomHook'
required:
- auditId
- event
- dateCreated
- customHook
additionalProperties: false
updatedMember:
type: object
properties:
id:
type: string
role:
type: string
environments:
type: array
items:
type: string
limitAccessByEnvironment:
type: boolean
additionalRoles:
description: >-
Additional roles granted alongside this one, in the same scope. Each
is granted independently and environment access is the union across
them.
type: array
items:
type: object
properties:
role:
type: string
environments:
type: array
items:
type: string
limitAccessByEnvironment:
type: boolean
required:
- role
- environments
additionalProperties: false
projectRoles:
type: array
items:
type: object
properties:
project:
type: string
role:
type: string
limitAccessByEnvironment:
type: boolean
environments:
type: array
items:
type: string
additionalRoles:
description: >-
Additional roles granted alongside this one, in the same
scope. Each is granted independently and environment access is
the union across them.
type: array
items:
type: object
properties:
role:
type: string
environments:
type: array
items:
type: string
limitAccessByEnvironment:
type: boolean
required:
- role
- environments
additionalProperties: false
required:
- project
- role
- limitAccessByEnvironment
- environments
additionalProperties: false
required:
- id
- role
- environments
- limitAccessByEnvironment
additionalProperties: false
approvalFlows:
type: object
properties:
savedGroups:
type: array
items:
$ref: '#/components/schemas/SavedGroupApprovalRule'
required:
- savedGroups
additionalProperties: false
monitoring:
type: object
properties:
enabled:
type: boolean
monitoringMode:
type: string
enum:
- auto
- manual
autoUpdate:
type: boolean
effectiveAutoUpdate:
type: boolean
blockedReason:
anyOf:
- type: string
- type: 'null'
currentStepMonitored:
type: boolean
nextSnapshotAt:
anyOf:
- type: string
- type: 'null'
safeRolloutId:
description: Internal ID of the linked monitoring experiment.
anyOf:
- type: string
- type: 'null'
required:
- enabled
- monitoringMode
- autoUpdate
- effectiveAutoUpdate
- currentStepMonitored
additionalProperties: false
healthSummary:
description: >-
Populated when monitoring is enabled and analysis data is available.
Contains the current evaluator decision, aggregate traffic health, and
per-metric status with effect sizes.
type: object
properties:
safeToAdvance:
description: >-
True only when every hold condition is cleared: the step interval
has elapsed, any required approval has been granted, min sample size
is met, and all monitored metrics are within bounds. Equivalent to
`decision === 'advance'`.
type: boolean
decision:
description: >-
Current evaluator decision for the active step. Incorporates all
hold conditions (timing, approval, min sample, metric health). When
monitoring data is not yet available, the evaluator returns `hold`
with a descriptive `decisionReason`.
type: string
enum:
- advance
- hold
- rollback
- pause
decisionReason:
description: Human-readable reason for a hold, rollback, or pause decision.
type: string
signals:
description: >-
All active health signals, not just the top-priority one. Useful for
surfacing multiple concurrent issues (e.g. SRM + guardrail failing
simultaneously). `healthy` is the sole entry when no issues are
detected.
type: array
items:
type: string
enum:
- guardrail-failing
- signal-regression
- srm
- multiple-exposures
- no-traffic
- below-min-sample
- healthy
- awaiting-data
snapshotAt:
description: ISO timestamp of the most recent successful analysis snapshot.
type: string
traffic:
description: >-
Traffic health from the latest snapshot. Absent when no snapshot has
been taken yet.
type: object
properties:
totalUsers:
description: Total unique users across all variations.
type: number
variationUnits:
description: >-
Per-variation user counts. Index 0 = baseline arm (users
continuing to see the existing behavior — either the configured
control value on a v1 safe rollout, or users passed through to
subsequent rules / feature default on a v2 monitored ramp).
Index 1 = treatment arm (users exposed to the new rollout
value).
type: array
items:
type: number
srm:
type: object
properties:
pValue:
description: SRM p-value from the traffic query.
type: number
status:
description: >-
`failing` when p-value is below the org SRM threshold,
indicating a traffic imbalance.
type: string
enum:
- ok
- failing
required:
- pValue
- status
additionalProperties: false
multipleExposures:
type: object
properties:
count:
description: Number of users exposed to both variations.
type: number
percent:
description: Fraction of total users with multiple exposures (0–1).
type: number
status:
type: string
enum:
- ok
- warning
required:
- count
- percent
- status
additionalProperties: false
required:
- totalUsers
- variationUnits
additionalProperties: false
metrics:
description: >-
Per-metric health keyed by metric ID. Only includes metrics
configured as guardrails or signals on this schedule.
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
id:
description: Metric ID.
type: string
name:
description: >-
Human-readable metric name. Absent if the metric definition
has been deleted.
type: string
status:
description: >-
`failing` = statistically significant regression;
`within-bounds` = no significant harm detected;
`not-enough-data` = insufficient data to evaluate.
type: string
enum:
- failing
- within-bounds
- not-enough-data
role:
description: >-
Whether this metric is a guardrail (triggers rollback on loss)
or a signal (triggers hold on loss).
type: string
enum:
- guardrail
- signal
relativeLift:
description: >-
Expected relative lift of the treatment arm vs the baseline
arm (e.g. 0.05 = +5%). See `traffic.variationUnits` for what
each arm represents.
type: number
absoluteLift:
description: >-
Absolute difference in conversion rate between the treatment
and baseline arms.
type: number
ciHarmBound:
description: >-
One-tailed CI bound in the direction of potential harm. For
normal metrics (higher is better) this is the lower CI bound;
for inverse metrics (lower is better, e.g. errors, latency)
this is the upper CI bound. Values further from zero in the
harmful direction indicate greater potential regression.
type: number
pValue:
description: >-
Two-sided p-value for the metric effect. Only present when the
stats engine produces a frequentist result.
type: number
required:
- id
- status
- role
additionalProperties: false
required:
- safeToAdvance
- decision
- signals
- metrics
additionalProperties: false
targets:
type: object
properties:
id:
type: string
entityType:
type: string
enum:
- feature
entityId:
type: string
ruleId:
anyOf:
- type: string
- type: 'null'
environment:
deprecated: true
description: >-
Legacy disambiguator used alongside `ruleId` for pre-v2 ramps. May
be null on newer targets.
anyOf:
- type: string
- type: 'null'
status:
type: string
enum:
- pending-join
- active
activatingRevisionVersion:
description: >-
Feature revision version that activates this ramp; cleared once
published
anyOf:
- type: integer
- type: 'null'
required:
- id
- entityType
- entityId
- status
additionalProperties: false
startActions:
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'
required:
- ruleId
additionalProperties: false
required:
- targetType
- targetId
- patch
additionalProperties: false
steps:
type: object
properties:
interval:
description: >-
Hold duration in seconds before this step's gates are evaluated.
null = no time gate (advance as soon as holdConditions clear).
anyOf:
- type: number
exclusiveMinimum: 0
- type: 'null'
approvalNotes:
anyOf:
- type: string
- type: 'null'
monitored:
description: >-
When true, this step runs A/B traffic analysis while active.
Treatment = [0, coverage), control = [0.5, 0.5+coverage). Arms are
equal-sized and non-adjacent: step-ups only add users, never
reassign existing ones. The UI caps monitored-step coverage at 0.5
so control end never exceeds 1.0. The SDK uses explicit hash ranges
on the experiment rule to prevent bucketing shifts across
monitored/unmonitored transitions.
type: boolean
holdConditions:
type: object
properties:
minSampleSize:
type: integer
exclusiveMinimum: 0
requiresApproval:
type: boolean
additionalProperties: false
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'
required:
- ruleId
additionalProperties: false
required:
- targetType
- targetId
- patch
additionalProperties: false
required:
- interval
- actions
additionalProperties: false
endActions:
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'
required:
- ruleId
additionalProperties: false
required:
- targetType
- targetId
- patch
additionalProperties: false
lockdownConfig:
type: object
properties:
mode:
type: string
enum:
- none
- locked
required:
- mode
additionalProperties: false
featureDraftPublishFailures:
type: object
properties:
featureId:
type: string
revisionVersion:
type: number
reason:
type: string
required:
- featureId
- revisionVersion
- reason
additionalProperties: false
columns:
type: object
properties:
column:
type: string
name:
type: string
datatype:
type: string
required:
- column
- name
- datatype
additionalProperties: false
metrics:
type: object
properties:
metricId:
type: string
metricType:
type: string
needsUnit:
type: boolean
required:
- metricId
- metricType
- needsUnit
additionalProperties: false
values:
type: object
propertyNames:
type: string
additionalProperties:
type: array
items:
type: string
learnings:
type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
dateUpdated:
type: string
format: date-time
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
authors:
type: array
items:
type: string
title:
type: string
text:
type: string
tags:
type: array
items:
type: string
supportingExperimentIds:
type: array
items:
type: string
contradictingExperimentIds:
type: array
items:
type: string
projects:
type: array
items:
type: string
status:
type: string
source:
type: string
enum:
- ai
- manual
- api
similarity:
description: Cosine similarity of the learning to the query (0-1)
type: number
required:
- id
- dateCreated
- dateUpdated
- owner
- authors
- title
- text
- tags
- supportingExperimentIds
- contradictingExperimentIds
- projects
- status
- source
- similarity
additionalProperties: false
metadata:
description: >-
What the wizard learned about the environment it ran in — language,
packageManager, framework, versions. Open by design; do not rely on any
single key being present
type: object
propertyNames:
type: string
maxLength: 60
additionalProperties:
anyOf:
- type: string
maxLength: 500
- type: number
- type: boolean
- type: 'null'
artifacts:
type: object
properties:
kind:
type: string
enum:
- sdk-connection
- feature
- experiment
- attribute
- metric
- fact-table
- saved-group
- environment
- tag
id:
type: string
label:
type: string
by:
type: string
enum:
- developer
- growthbook
detail:
anyOf:
- type: string
- type: 'null'
externalId:
description: Id in the system this was imported from, when it was imported
anyOf:
- type: string
- type: 'null'
action:
description: What the run did to this object
type: string
enum:
- created
- updated
- existing
- deleted
- failed
dateCreated:
type: string
format: date-time
required:
- kind
- id
- label
- by
- detail
- dateCreated
additionalProperties: false
checks:
type: object
properties:
name:
type: string
maxLength: 100
ok:
type: boolean
required:
type: boolean
required:
- name
- ok
- required
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
```
x-tagGroups:
- name: Endpoints
tags:
- projects
- environments
- features-v2
- feature-revisions-v2
- features
- feature-revisions
- ramp-schedules
- data-sources
- fact-tables
- fact-metrics
- metrics
- experiments
- namespaces
- snapshots
- dimensions
- segments
- reports
- sdk-connections
- visual-changesets
- saved-groups
- saved-group-revisions
- constants
- constant-revisions
- configs
- config-revisions
- releases
- custom-hooks
- organizations
- members
- code-references
- archetypes
- queries
- settings
- attributes
- usage
- meta
- ContextualBandits
- Dashboards
- ContextualBanditQueries
- Interleavings
- CustomFields
- MetricGroups
- Teams
- ExperimentTemplates
- AnalyticsExplorations
- RampScheduleTemplates
- Learnings
- Holdouts
- AutoRuns
- Populations
- name: Models
tags:
- AggregatedFactTable_model
- AnalyticsExploration_model
- Archetype_model
- Attribute_model
- AutoRun_model
- CodeRef_model
- Config_model
- ConfigKeyUsage_model
- ConfigLineage_model
- ConfigReferences_model
- ConfigRevision_model
- ConfigRevisionActivityLogEntry_model
- ConfigRevisionRef_model
- ConfigRevisionReview_model
- ConfigSchemaExport_model
- ConfigSchemaSource_model
- ConfigSchemaVerify_model
- ConfigSchemaWarning_model
- Confirmation_model
- ConfirmationHeld_model
- Constant_model
- ConstantReferences_model
- ConstantRevision_model
- ConstantRevisionActivityLogEntry_model
- ConstantRevisionRef_model
- ConstantRevisionReview_model
- ContextualBandit_model
- ContextualBanditQuery_model
- CustomField_model
- CustomHook_model
- Dashboard_model
- DataSource_model
- Dimension_model
- Environment_model
- EventUser_model
- Experiment_model
- Experiment Rule_model
- ExperimentAnalysisSettings_model
- ExperimentDecisionFrameworkSettings_model
- ExperimentMetric_model
- ExperimentMetricOverrideEntry_model
- ExperimentResults_model
- ExperimentSnapshot_model
- ExperimentTemplate_model
- ExperimentWithEnhancedStatus_model
- FactMetric_model
- FactTable_model
- FactTableColumn_model
- FactTableFilter_model
- FeatureBaseRule_model
- FeatureContextualBanditRefRule_model
- FeatureDefinition_model
- FeatureEnvironmentV1_model
- FeatureEnvironmentV2_model
- FeatureExperimentRefRule_model
- FeatureExperimentRule_model
- FeatureForceRule_model
- FeatureRevisionRef_model
- FeatureRevisionSummary_model
- FeatureRevisionV1_model
- FeatureRevisionV2_model
- FeatureRolloutRule_model
- FeatureRuleV1_model
- FeatureRuleV2_model
- FeatureSafeRolloutRule_model
- FeatureV1_model
- FeatureV2_model
- FeatureWithRevisionsV1_model
- FeatureWithRevisionsV2_model
- Holdout_model
- InformationSchema_model
- InformationSchemaTable_model
- Interleaving_model
- Learning_model
- LookbackOverride_model
- Member_model
- Metric_model
- MetricAnalysis_model
- MetricGroup_model
- MetricUsage_model
- Namespace_model
- NamespaceExperimentMember_model
- Organization_model
- PaginationFields_model
- Population_model
- Project_model
- Query_model
- RampSchedule_model
- RampScheduleTemplate_model
- Report_model
- RequireReviewRule_model
- RequireReviewRuleInput_model
- RevisionIdRef_model
- Safe Rollout Rule_model
- SavedGroup_model
- SavedGroupApprovalRule_model
- SavedGroupReferenceResource_model
- SavedGroupReferences_model
- SavedGroupRevision_model
- SavedGroupRevisionActivityLogEntry_model
- SavedGroupRevisionRef_model
- SavedGroupRevisionReview_model
- SavedGroupUpload_model
- ScheduleRule_model
- ScheduledStopPlan_model
- SdkConnection_model
- Segment_model
- Settings_model
- Targeting Rule_model
- TargetingReviewRule_model
- Team_model
- VisualChange_model
- VisualChangeset_model
- VisualEditorCbExperimentStub_model