Skip to main content
API docs by Redocly

GrowthBook REST API (5.0.0)

Download OpenAPI specification:Download

GrowthBook offers a full REST API for interacting with the application.

Request data can use either JSON or Form data encoding (with proper Content-Type headers). All response bodies are JSON-encoded.

The API base URL for GrowthBook Cloud is https://api.growthbook.io/api. For self-hosted deployments, it is the same as your API_HOST environment variable (defaults to http://localhost:3100/api). The rest of these docs will assume you are using GrowthBook Cloud.

Versioning

Endpoints are versioned by path prefix:

  • /v1/... — stable, widely-supported endpoints
  • /v2/... — updated endpoints with improved shapes (e.g. unified per-rule environment scope for feature flags)

New integrations should prefer v2 where available.

Authentication

We support both the HTTP Basic and Bearer authentication schemes for convenience.

You first need to generate a new API Key in GrowthBook. Different keys have different permissions:

  • Personal Access Tokens: These are sensitive and provide the same level of access as the user has to an organization. These can be created by going to Personal Access Tokens under the your user menu.
  • Secret Keys: These are sensitive and provide the level of access for the role, which currently is either admin or readonly. Only Admins with the manageApiKeys permission can manage Secret Keys on behalf of an organization. These can be created by going to Settings -> API Keys

If using HTTP Basic auth, pass the Secret Key as the username and leave the password blank (when using curl, add : at the end of the secret to indicate an empty password)

curl https://api.growthbook.io/api/v1/features \
  -u secret_abc123DEF456:

If using Bearer auth, pass the Secret Key as the token:

curl https://api.growthbook.io/api/v1/features \
-H "Authorization: Bearer secret_abc123DEF456"

Errors

The API may return the following error status codes:

  • 400 - Bad Request - Often due to a missing required parameter
  • 401 - Unauthorized - No valid API key provided
  • 402 - Request Failed - The parameters are valid, but the request failed
  • 403 - Forbidden - Provided API key does not have the required access
  • 404 - Not Found - Unknown API route or requested resource
  • 422 - Soft Warning - The request failed, but can be re-submitted with "ignoreWarnings": true in the request body to proceed anyway. Blocked publishes include a gates array, one entry per blocking gate, each carrying a uniform set of fields: type, severity, messages, override (the body flag that clears it — ignoreWarnings for acknowledge-class warnings, or the privileged skipSchemaValidation (schema/invariant/schema-break) / skipHooks (custom-hook rejections), or null when no flag applies), requiresPermission (a permission the override needs, or null), and resolution (the non-flag way out as a callable { action, method, path } route, or null). So one response lists every way past every gate. A gate with override: null (approval required) clears by getting the revision approved, or implicitly for callers with the bypassApprovalChecks permission; a locked config clears by calling its resolution unlock route. On a SUCCESSFUL publish (200), if a gate that would have blocked was bypassed by the caller's authority, the response includes a bypassedGates array ({ type, outcome: "bypassed", via }, where via is ignoreWarnings, skipSchemaValidation, skipHooks, bypassApprovalChecks, or restApiBypassesReviews); the key is omitted when nothing was bypassed.
  • 429 - Too Many Requests - You exceeded the rate limit of 60 requests per minute. Try again later.
  • 5XX - Server Error - Something went wrong on GrowthBook's end (these are rare)

The response body will be a JSON object with the following properties:

  • message - Information about the error

Projects

Projects are used to organize your feature flags and experiments

Get all projects

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/projects' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "projects": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a single project

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
name
required
string
description
string <= 10000 characters
publicId
string

URL-safe slug (lowercase letters, numbers, dashes). Auto-generated from name if not provided.

object

Project stats settings that, when set, override the organization settings.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "publicId": "string",
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "project": {
    }
}

Get a single project

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/projects/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "project": {
    }
}

Edit a single project

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
name
string

Project name.

description
string <= 10000 characters

Project description.

publicId
string

URL-safe slug (lowercase letters, numbers, dashes).

object

Project stats settings that, when set, override the organization settings.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "publicId": "string",
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "project": {
    }
}

Deletes a single project

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/projects/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "prj__123abc"
}

Environments

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.

Get the organization's environments

Authorizations:
bearerAuthbasicAuth

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/environments' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "environments": [
    ]
}

Create a new environment

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
id
required
string

The ID of the new environment

description
string

The description of the new environment

toggleOnList
boolean

Show on feature list page

defaultState
boolean

Default state for new features

projects
Array of strings
parent
string

An environment that the new environment should inherit feature rules from. Requires an enterprise license

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "description": "string",
  • "toggleOnList": true,
  • "defaultState": true,
  • "projects": [
    ],
  • "parent": "string"
}

Response samples

Content type
application/json
{
  • "environment": {
    }
}

Update an environment

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
description
string

The description of the new environment

toggleOnList
boolean

Show on feature list page

defaultState
boolean

Default state for new features

projects
Array of strings

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "toggleOnList": true,
  • "defaultState": true,
  • "projects": [
    ]
}

Response samples

Content type
application/json
{
  • "environment": {
    }
}

Deletes a single environment

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/environments/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "string"
}

Feature Flags

Control your feature flags programatically.

Rules are returned as a unified top-level array; each rule carries allEnvironments / environments scope fields instead of being bucketed by environment.

Get all features

Returns features with pagination. Rules are returned as a unified top-level array with per-rule environment scope.

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

projectId
string

Filter by project id

clientKey
string

Filter by a SDK connection's client key

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean

Whether to include archived features. Defaults to false (non-archived only). Pass true to include archived features alongside non-archived ones.

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Default: false

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.

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v2/features' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "features": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a single feature

Creates a new feature. Rules are supplied as a top-level rules array; each rule includes allEnvironments / environments scope fields.

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: "<configKey>" to put the 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:

{
  "id": "checkout-config",
  "valueType": "json",
  "baseConfig": "purchase-flow",
  "defaultValue": "{}",
  "rules": [
    { "type": "force", "config": "purchase-flow-vip", "value": "{\"maxItems\": 20}", "allEnvironments": true }
  ]
}
Authorizations:
bearerAuthbasicAuth
query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass skipSchemaValidation in the request body instead.

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass ignoreWarnings in the request body instead.

Request Body schema: application/json
required
id
required
string non-empty

A unique key name for the feature. Feature keys can only include letters, numbers, hyphens, and underscores.

archived
boolean
description
string <= 10000 characters

Description of the feature

owner
string

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.

project
string

An associated project ID

targetingAllProjects
boolean

Make this feature discoverable in — and served to — every project, beyond its primary project. Governance/approvals stay with project.

targetingProjects
Array of strings

Secondary project IDs this feature is targeted in and served to, beyond its primary project. Governance/approvals stay with project.

valueType
required
string
Enum: "boolean" "string" "number" "json"

The data type of the feature payload. Boolean by default.

defaultValue
required
string

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.

string or null

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.

string or null

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.

tags
Array of strings

List of associated tags

Array of objects or objects or objects or objects

Feature rules. Each rule carries its own environment scope via allEnvironments / environments.

object

Per-environment enabled state. V2 rules are specified on the top-level rules field.

prerequisites
Array of strings

Feature IDs. Each feature must evaluate to true

jsonSchema
string

Use JSON schema to validate the payload of a JSON-type feature value (enterprise only).

object
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "archived": true,
  • "description": "string",
  • "owner": "string",
  • "project": "string",
  • "targetingAllProjects": true,
  • "targetingProjects": [
    ],
  • "valueType": "boolean",
  • "defaultValue": "string",
  • "baseConfig": "string",
  • "defaultValueConfig": "string",
  • "tags": [
    ],
  • "rules": [
    ],
  • "environments": {
    },
  • "prerequisites": [
    ],
  • "jsonSchema": "string",
  • "customFields": {
    },
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "feature": {
    }
}

Get a single feature

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

query Parameters
withRevisions
string
Enum: "all" "drafts" "published" "none"

Also return feature revisions (all, draft, or published statuses)

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v2/features/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "feature": {
    }
}

Partially update a feature

Updates any combination of a feature's metadata, default value, environment state, and rules. Other top-level fields are patch-merged: omit a field to leave it unchanged. The rules field, when supplied, replaces the entire rules array atomically in a single revision (v1 PUT applied per-environment patches; v2 swaps the full flat array). To preserve existing rules during a partial edit, GET the feature first, mutate the returned rules array, and PUT the full array back. Safe-rollout rules round-trip via their safeRolloutId; use POST /v2/features/:id/revisions/:version/rules to create new ones. Returns 403 if approval rules are enabled for an affected environment and the bypass setting is off.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass skipSchemaValidation in the request body instead.

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass ignoreWarnings in the request body instead.

Request Body schema: application/json
required
description
string <= 10000 characters

Description of the feature

archived
boolean
project
string

An associated project ID

targetingAllProjects
boolean

Make this feature discoverable in — and served to — every project, beyond its primary project. Governance/approvals stay with project.

targetingProjects
Array of strings

Secondary project IDs this feature is targeted in and served to, beyond its primary project. Governance/approvals stay with project.

owner
string

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.

defaultValue
string
string or null

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.

string or null

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.

tags
Array of strings

List of associated tags. Will override tags completely with submitted list

Array of objects or objects or objects or objects

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).

object

Per-environment enabled state. V2 rules are specified on the top-level rules field.

prerequisites
Array of strings

Feature IDs. Each feature must evaluate to true

jsonSchema
string

Use JSON schema to validate the payload of a JSON-type feature value (enterprise only).

object
object or null

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.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "archived": true,
  • "project": "string",
  • "targetingAllProjects": true,
  • "targetingProjects": [
    ],
  • "owner": "string",
  • "defaultValue": "string",
  • "baseConfig": "string",
  • "defaultValueConfig": "string",
  • "tags": [
    ],
  • "rules": [
    ],
  • "environments": {
    },
  • "prerequisites": [
    ],
  • "jsonSchema": "string",
  • "customFields": {
    },
  • "holdout": {
    },
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "feature": {
    }
}

Deletes a single feature

Permanently deletes a feature and all of its revisions.

Archived features can be deleted freely. Deleting a live (non-archived) feature returns 403 unless the org setting "REST API always bypasses approval requirements" is enabled.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v2/features/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "feature-123"
}

Toggle a feature in one or more environments

Enables or disables a feature in one or more environments simultaneously. Accepts a map of environment name → boolean.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
reason
string
required
object

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "environments": {
    }
}

Response samples

Content type
application/json
{
  • "feature": {
    }
}

Revert a feature to a specific revision

Creates a new revision whose rules and values match a previously-published revision, then immediately publishes it, leaving a clear audit trail of the revert in the revision history.

Returns 403 if the API key lacks permission, or if approval rules are enabled for an affected environment and neither the "REST API always bypasses approval requirements" nor the "Allow reverts without approval" org setting is enabled.

Returns 422 with a list of warnings if the restored values no longer validate against the feature's current value type or JSON schema (e.g. reverting to a config the current schema can no longer read). Re-submit with "ignoreWarnings": true in the request body to revert anyway.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
revision
required
number
comment
string
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "revision": 0,
  • "comment": "string",
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "feature": {
    }
}

Get list of feature keys

Authorizations:
bearerAuthbasicAuth
query Parameters
projectId
string

Filter by project id

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v2/feature-keys' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
[
  • "string"
]

Get stale status for one or more features

Authorizations:
bearerAuthbasicAuth
query Parameters
ids
required
string

Comma-separated list of feature IDs (URL-encoded if needed). Example: my_feature,another_feature

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v2/stale-features' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "features": {
    }
}

Feature Revisions

Draft revisions for feature flags, including rules, scheduling, and approval workflows.

Revision rules is a flat array with per-rule scope fields.

List revisions across all features

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.

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Default: false

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.

featureId
string
string or Array of strings

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).

author
string
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean

If true, return only revisions authored by or contributed to by the calling user.

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean

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.

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v2/feature-revisions' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revisions": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

List revisions for a feature

Returns a paginated list of revisions for this feature, sorted newest-first. Revision rules is a flat array with per-rule scope.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Default: false

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.

string or Array of strings

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).

author
string
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean

If true, return only revisions authored by or contributed to by the calling user. Requires a user-scoped API key. Mutually exclusive with author.

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v2/features/{id}/revisions' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revisions": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a draft revision

Creates a new draft revision branched from the current live revision.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean

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.

Request Body schema: application/json
required
comment
string
title
string
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "comment": "string",
  • "title": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Get the most recent active draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean

If true, return only the most recent active draft authored by or contributed to by the calling user.

string or Array of strings

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).

author
string

Filter to drafts created by this user (userId).

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v2/features/{id}/revisions/latest' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Get a single feature revision

Returns the revision at the specified version for this feature. Revision rules is a flat array with per-rule environment scope.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Diff a revision against another revision

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=<version> for an arbitrary historical one.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
query Parameters
format
string
Enum: "minimal" "full"

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.

"baseVersion" (string) or "live" (string) or integer

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).

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/diff' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "diff": {
    }
}

Update revision metadata

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
comment
string
title
string
description
string
owner
string

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.

project
string
tags
Array of strings
neverStale
boolean
object
object
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "comment": "string",
  • "title": "string",
  • "description": "string",
  • "owner": "string",
  • "project": "string",
  • "tags": [
    ],
  • "neverStale": true,
  • "customFields": {
    },
  • "jsonSchema": {
    },
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Set the default value in a draft revision

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass skipSchemaValidation in the request body instead.

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass ignoreWarnings in the request body instead.

Request Body schema: application/json
required
defaultValue
required
string

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.

string or null

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.

revisionTitle
string

Title for a newly created draft. Only used when version is "new"; ignored for existing revisions.

revisionComment
string

Comment for a newly created draft. Only used when version is "new"; ignored for existing revisions.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "defaultValue": "string",
  • "defaultValueConfig": "string",
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Set feature-level prerequisites in a draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
required
Array of objects

List of prerequisite boolean flags. When any prerequisite flag is off for a user, this flag returns its defaultValue for that user.

revisionTitle
string

Title for a newly created draft. Only used when version is "new"; ignored for existing revisions.

revisionComment
string

Comment for a newly created draft. Only used when version is "new"; ignored for existing revisions.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "prerequisites": [
    ],
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Set holdout in a draft revision

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
required
object or null
revisionTitle
string

Title for a newly created draft. Only used when version is "new"; ignored for existing revisions.

revisionComment
string

Comment for a newly created draft. Only used when version is "new"; ignored for existing revisions.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "holdout": {
    },
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Set archived state in a draft revision

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
archived
required
boolean
revisionTitle
string

Title for a newly created draft. Only used when version is "new"; ignored for existing revisions.

revisionComment
string

Comment for a newly created draft. Only used when version is "new"; ignored for existing revisions.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "archived": true,
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Toggle an environment on/off in a draft revision

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
environment
required
string
enabled
required
boolean
revisionTitle
string

Title for a newly created draft. Only used when version is "new"; ignored for existing revisions.

revisionComment
string

Comment for a newly created draft. Only used when version is "new"; ignored for existing revisions.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "environment": "string",
  • "enabled": true,
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Add a rule to a draft revision

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).

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass skipSchemaValidation in the request body instead.

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass ignoreWarnings in the request body instead.

Request Body schema: application/json
required
required
Targeting Rule (object) or Experiment Rule (object) or Safe Rollout Rule (object)
object

Multi-step ramp schedule for force/rollout rules. Not supported for experiment-ref or safe-rollout rules. Mutually exclusive with schedule.

object

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.

revisionTitle
string

Title for a newly created draft. Only used when version is "new"; ignored for existing revisions.

revisionComment
string

Comment for a newly created draft. Only used when version is "new"; ignored for existing revisions.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "rule": {
    },
  • "rampSchedule": {
    },
  • "schedule": {
    },
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Update a rule in a draft revision

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).

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
ruleId
required
string
query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass skipSchemaValidation in the request body instead.

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass ignoreWarnings in the request body instead.

Request Body schema: application/json
required
required
object
object

Multi-step ramp schedule for force/rollout rules. Not supported for experiment-ref or safe-rollout rules. Mutually exclusive with schedule.

object

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.

revisionTitle
string

Title for a newly created draft. Only used when version is "new"; ignored for existing revisions.

revisionComment
string

Comment for a newly created draft. Only used when version is "new"; ignored for existing revisions.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "rule": {
    },
  • "rampSchedule": {
    },
  • "schedule": {
    },
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Delete a rule from a draft revision

Removes the rule from the revision. Any pending ramp actions for this rule are also cleared.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
ruleId
required
string
Request Body schema: application/json
required
revisionTitle
string

Title for a newly created draft. Only used when version is "new"; ignored for existing revisions.

revisionComment
string

Comment for a newly created draft. Only used when version is "new"; ignored for existing revisions.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Reorder rules in the revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
ruleIds
required
Array of strings
revisionTitle
string

Title for a newly created draft. Only used when version is "new"; ignored for existing revisions.

revisionComment
string

Comment for a newly created draft. Only used when version is "new"; ignored for existing revisions.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "ruleIds": [
    ],
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Set ramp schedule for a rule

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%.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
ruleId
required
string
Request Body schema: application/json
required
name
string
templateId
string
Array of objects
Array of objects
Array of objects
string or null

ISO 8601 date-time, e.g. "2025-06-01T00:00:00Z". Absent or null means start immediately on publish.

string or null

ISO 8601 date-time, e.g. "2025-07-01T00:00:00Z". The ramp ends at this time.

object
object
boolean or null
environment
string
Deprecated
object

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%. This affects rollbacks only — it is NOT applied when the ramp starts. 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.

revisionTitle
string

Title for a newly created draft. Only used when version is "new"; ignored for existing revisions.

revisionComment
string

Comment for a newly created draft. Only used when version is "new"; ignored for existing revisions.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "templateId": "string",
  • "startActions": [
    ],
  • "steps": [
    ],
  • "endActions": [
    ],
  • "startDate": "2019-08-24T14:15:22Z",
  • "cutoffDate": "2019-08-24T14:15:22Z",
  • "monitoringConfig": {
    },
  • "lockdownConfig": {
    },
  • "requiresStartApproval": true,
  • "environment": "string",
  • "startState": {
    },
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    },
  • "warnings": [
    ]
}

Remove ramp schedule from a rule

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
ruleId
required
string
Request Body schema: application/json
required
revisionTitle
string

Title for a newly created draft. Only used when version is "new"; ignored for existing revisions.

revisionComment
string

Comment for a newly created draft. Only used when version is "new"; ignored for existing revisions.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Request review for a draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
Request Body schema: application/json
required
comment
string
autoPublishOnApproval
boolean
string or null
scheduledPublishLockEdits
boolean
scheduledPublishLockOthers
boolean

Responses

Request samples

Content type
application/json
{
  • "comment": "string",
  • "autoPublishOnApproval": true,
  • "scheduledPublishAt": "2019-08-24T14:15:22Z",
  • "scheduledPublishLockEdits": true,
  • "scheduledPublishLockOthers": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Schedule (or cancel) a deferred publish for a draft revision

Arms a deferred publish: the revision publishes automatically on/after scheduledPublishAt (and, when review is required, only once also approved). Send scheduledPublishAt: null to cancel the schedule.

Use lockEdits to freeze content edits to this draft while the schedule is pending (rebasing is still allowed), and lockOthers to block publishing other drafts of this feature until the schedule fires or is canceled. Requires publish permission; the publish executes with the caller's authority. An admin with bypass-approval permission can schedule even without approval — pass bypassApproval: true to mark it as an admin override, which locks the schedule to cancel-and-re-arm only.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
Request Body schema: application/json
required
required
string or null
lockEdits
boolean
lockOthers
boolean
bypassApproval
boolean

Responses

Request samples

Content type
application/json
{
  • "scheduledPublishAt": "2019-08-24T14:15:22Z",
  • "lockEdits": true,
  • "lockOthers": true,
  • "bypassApproval": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Submit a review on a draft revision

Submits an approve, request-changes, or comment review on the draft. 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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
Request Body schema: application/json
required
comment
string
action
string
Enum: "approve" "request-changes" "comment"
skipAutoPublish
boolean

Responses

Request samples

Content type
application/json
{
  • "comment": "string",
  • "action": "approve",
  • "skipAutoPublish": true
}

Response samples

Content type
application/json
{
  • "revision": {
    },
  • "autoPublished": true
}

Recall a review request (revert to draft)

Retracts the review request, returning the revision from pending-review, changes-requested, or approved back to draft. Allowed for any user with draft-management permission on the feature (the same permission required to request review), not only the original requester. Existing review log entries are preserved as audit history but any in-flight reviewer verdicts (Approved / Requested Changes) submitted during this review cycle no longer count — submitting a fresh request-review starts a new cycle.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Undo a reviewer's own review verdict

Reviewer retracts their own verdict. 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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "revision": {
    }
}

List the activity log for a revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/log' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "log": [
    ]
}

Edit the comment text of an owned log entry

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
logId
required
string
Request Body schema: application/json
required
comment
required
string

New comment text. Replaces existing comment text.

Responses

Request samples

Content type
application/json
{
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "status": 200
}

Delete an owned revision Comment entry

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
logId
required
string
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "status": 200
}

Get merge status for a draft revision

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.<ruleId>, 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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/merge-status' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "success": true,
  • "liveVersion": 0,
  • "draftDateUpdated": "2019-08-24T14:15:22Z",
  • "conflicts": [
    ],
  • "result": {
    },
  • "rebaseRequired": true
}

Preview a rebase without applying it

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
Request Body schema: application/json
required
object

Map of conflict key → resolution. Keys come from the returned conflicts: defaultValue, prerequisites, archived, holdout, environmentsEnabled.<env>, metadata.<field>, rules.<ruleId>, 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.

expectedLiveVersion
integer

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.

expectedDraftDateUpdated
string

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.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "conflictResolutions": {
    },
  • "expectedLiveVersion": 0,
  • "expectedDraftDateUpdated": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "liveVersion": 0,
  • "draftDateUpdated": "2019-08-24T14:15:22Z",
  • "conflicts": [
    ],
  • "result": {
    }
}

Rebase a draft revision onto the current live version

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.<ruleId>) 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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
Request Body schema: application/json
required
object

Map of conflict key → resolution. Keys come from the returned conflicts: defaultValue, prerequisites, archived, holdout, environmentsEnabled.<env>, metadata.<field>, rules.<ruleId>, 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.

expectedLiveVersion
integer

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.

expectedDraftDateUpdated
string

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.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "conflictResolutions": {
    },
  • "expectedLiveVersion": 0,
  • "expectedDraftDateUpdated": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Publish a draft revision

Immediately publishes a draft revision, making it the live version of the feature. Any pending ramp actions (pendingRamp on rules) are executed atomically — ramp schedules are created or detached as queued.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass skipSchemaValidation in the request body instead.

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass ignoreWarnings in the request body instead.

Request Body schema: application/json
required
comment
string
bypassApproval
boolean

Has no effect and is accepted only for backwards compatibility. Callers with the bypassApprovalChecks permission (or under the org-level REST bypass setting) bypass approval requirements automatically; all other callers must have the revision approved before publishing.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "comment": "string",
  • "bypassApproval": true,
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "revision": {
    },
  • "bypassedGates": [
    ]
}

Discard a draft revision

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Reopen a discarded revision as a draft

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Revert the feature to a prior revision

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
Request Body schema: application/json
required
strategy
string
Enum: "draft" "publish"
comment
string
title
string

Responses

Request samples

Content type
application/json
{
  • "strategy": "draft",
  • "comment": "string",
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Feature Flags (legacy)

Control your feature flags programatically.

These are v1 endpoints. New integrations should use the v2 Feature Flags endpoints, which expose a unified per-rule environment scope instead of per-environment rule arrays.

Get all features Deprecated

Deprecated. Use GET /v2/features instead.

Returns features with pagination. The skipPagination query parameter is honored only when API_ALLOW_SKIP_PAGINATION is set (self-hosted deployments).

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

projectId
string

Filter by project id

clientKey
string

Filter by a SDK connection's client key

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Default: false

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.

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/features' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "features": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a single feature Deprecated

Deprecated. Use POST /v2/features instead.

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
id
required
string non-empty

A unique key name for the feature. Feature keys can only include letters, numbers, hyphens, and underscores.

archived
boolean
description
string <= 10000 characters

Description of the feature

owner
string

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.

project
string

An associated project ID

targetingAllProjects
boolean

Make this feature discoverable in — and served to — every project, beyond its primary project. Governance/approvals stay with project.

targetingProjects
Array of strings

Secondary project IDs this feature is targeted in and served to, beyond its primary project. Governance/approvals stay with project.

valueType
required
string
Enum: "boolean" "string" "number" "json"

The data type of the feature payload. Boolean by default.

defaultValue
required
string

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.

string or null

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.

tags
Array of strings

List of associated tags

object

A dictionary of environments that are enabled for this feature. Keys supply the names of environments. Environments belong to organization and are not specified will be disabled by default.

prerequisites
Array of strings

Feature IDs. Each feature must evaluate to true

jsonSchema
string

Use JSON schema to validate the payload of a JSON-type feature value (enterprise only).

object
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "archived": true,
  • "description": "string",
  • "owner": "string",
  • "project": "string",
  • "targetingAllProjects": true,
  • "targetingProjects": [
    ],
  • "valueType": "boolean",
  • "defaultValue": "string",
  • "baseConfig": "string",
  • "tags": [
    ],
  • "environments": {
    },
  • "prerequisites": [
    ],
  • "jsonSchema": "string",
  • "customFields": {
    },
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "feature": {
    }
}

Get a single feature Deprecated

Deprecated. Use GET /v2/features/:id instead.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

query Parameters
withRevisions
string
Enum: "all" "drafts" "published" "none"

Also return feature revisions (all, draft, or published statuses)

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/features/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "feature": {
    }
}

Partially update a feature Deprecated

Deprecated. Use POST /v2/features/:id instead.

Updates any combination of a feature's metadata (description, owner, tags, project), default value, environment settings (rules, kill switches, enabled state), prerequisites, holdout assignment, or JSON schema validation. All provided fields are merged into the existing feature and the result is immediately published as a new revision.

Returns 403 if the API key lacks permission or if approval rules are enabled for an affected environment and the org setting "REST API always bypasses approval requirements" is off.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
description
string <= 10000 characters

Description of the feature

archived
boolean
project
string

An associated project ID

targetingAllProjects
boolean

Make this feature discoverable in — and served to — every project, beyond its primary project. Governance/approvals stay with project.

targetingProjects
Array of strings

Secondary project IDs this feature is targeted in and served to, beyond its primary project. Governance/approvals stay with project.

owner
string

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.

defaultValue
string
string or null

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.

tags
Array of strings

List of associated tags. Will override tags completely with submitted list

object
prerequisites
Array of strings

Feature IDs. Each feature must evaluate to true

jsonSchema
string

Use JSON schema to validate the payload of a JSON-type feature value (enterprise only).

object
object or null

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.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "archived": true,
  • "project": "string",
  • "targetingAllProjects": true,
  • "targetingProjects": [
    ],
  • "owner": "string",
  • "defaultValue": "string",
  • "baseConfig": "string",
  • "tags": [
    ],
  • "environments": {
    },
  • "prerequisites": [
    ],
  • "jsonSchema": "string",
  • "customFields": {
    },
  • "holdout": {
    },
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "feature": {
    }
}

Deletes a single feature Deprecated

Deprecated. Use DELETE /v2/features/:id instead.

Permanently deletes a feature and all of its revisions.

Archived features can be deleted freely. Deleting a live (non-archived) feature returns 403 unless the org setting "REST API always bypasses approval requirements" is enabled, or the API key lacks delete permission.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/features/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "feature-123"
}

Toggle a feature in one or more environments Deprecated

Deprecated. Use POST /v2/features/:id/toggle instead.

Enables or disables a feature in one or more environments simultaneously. Accepts a map of environment name → boolean and immediately publishes the change.

Returns 403 if the API key lacks permission or if approval rules are enabled for an affected environment and the org setting "REST API always bypasses approval requirements" is off.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
reason
string
required
object

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "environments": {
    }
}

Response samples

Content type
application/json
{
  • "feature": {
    }
}

Revert a feature to a specific revision Deprecated

Deprecated. Use POST /v2/features/:id/revert instead.

Creates a new revision whose rules and values match a previously-published revision, then immediately publishes it. This leaves a clear audit trail of the revert action in the revision history.

Returns 403 if the API key lacks permission, or if approval rules are enabled for an affected environment and neither the "REST API always bypasses approval requirements" nor the "Allow reverts without approval" org setting is enabled.

Returns 422 with a list of warnings if the restored values no longer validate against the feature's current value type or JSON schema. Re-submit with "ignoreWarnings": true in the request body to revert anyway.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
revision
required
number
comment
string
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "revision": 0,
  • "comment": "string",
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "feature": {
    }
}

Get list of feature keys Deprecated

Deprecated. Use GET /v2/feature-keys instead.

Authorizations:
bearerAuthbasicAuth
query Parameters
projectId
string

Filter by project id

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/feature-keys' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
[
  • "string"
]

Get stale status for one or more features Deprecated

Deprecated. Use GET /v2/stale-features instead.

Authorizations:
bearerAuthbasicAuth
query Parameters
ids
required
string

Comma-separated list of feature IDs (URL-encoded if needed). Example: my_feature,another_feature

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/stale-features' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "features": {
    }
}

Feature Revisions (legacy)

Draft revisions for feature flags, including rules, scheduling, and approval workflows.

These are v1 endpoints. New integrations should use the v2 Feature Revisions endpoints.

List feature revisions Deprecated

Deprecated. Use GET /v2/feature-revisions 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.

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Default: false

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.

featureId
string
string or Array of strings

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).

author
string
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean

If true, return only revisions authored by or contributed to by the calling user. Requires a user-scoped API key. Mutually exclusive with author.

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/revisions' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revisions": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

List revisions for a feature Deprecated

Deprecated. Use GET /v2/features/:id/revisions instead.

Returns a paginated list of revisions for this feature, sorted newest-first. Optionally filtered by status and/or author.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Default: false

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.

string or Array of strings

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).

author
string

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/features/abc123/revisions' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revisions": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a draft revision Deprecated

Deprecated. Use POST /v2/features/:id/revisions 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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean

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.

Request Body schema: application/json
required
comment
string
title
string
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "comment": "string",
  • "title": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Get the most recent active draft revision Deprecated

Deprecated. Use GET /v2/features/:id/revisions/latest 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 (requires a user-scoped API key).

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean

If true, return only the most recent active draft authored by or contributed to by the calling user. Requires a user-scoped API key.

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/features/{id}/revisions/latest' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Get a single feature revision Deprecated

Deprecated. Use GET /v2/features/:id/revisions/:version instead.

Returns the revision at the specified version for this feature. Use GET /features/{id}/revisions/latest for the most recent active draft.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Update revision metadata (comment, title, feature metadata) Deprecated

Deprecated. Use PUT /v2/features/:id/revisions/:version/metadata 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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
comment
string
title
string
description
string
owner
string

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.

project
string
tags
Array of strings
neverStale
boolean
object
object
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "comment": "string",
  • "title": "string",
  • "description": "string",
  • "owner": "string",
  • "project": "string",
  • "tags": [
    ],
  • "neverStale": true,
  • "customFields": {
    },
  • "jsonSchema": {
    },
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Set the default value in a draft revision Deprecated

Deprecated. Use PUT /v2/features/:id/revisions/:version/default-value 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).

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
defaultValue
required
string
revisionTitle
string
revisionComment
string
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "defaultValue": "string",
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Set feature-level prerequisites in a draft revision Deprecated

Deprecated. Use PUT /v2/features/:id/revisions/:version/prerequisites instead.

Replaces the feature's prerequisite list for this revision. Each prerequisite condition is evaluated against { value: <prereq-flag-value> } at SDK eval time — use value as the condition key.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
required
Array of objects
revisionTitle
string
revisionComment
string
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "prerequisites": [
    ],
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Set holdout in a draft revision Deprecated

Deprecated. Use PUT /v2/features/:id/revisions/:version/holdout 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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
required
object or null
revisionTitle
string
revisionComment
string
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "holdout": {
    },
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Set archived state in a draft revision Deprecated

Deprecated. Use PUT /v2/features/:id/revisions/:version/archive instead.

Sets whether the feature is archived. Archived features are excluded from SDK payloads on publish.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
archived
required
boolean
revisionTitle
string
revisionComment
string
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "archived": true,
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Toggle an environment on/off in a draft revision Deprecated

Deprecated. Use POST /v2/features/:id/revisions/:version/toggle instead.

Sets whether the feature is enabled in the given environment as part of the draft. Takes effect on publish.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
environment
required
string
enabled
required
boolean
revisionTitle
string
revisionComment
string
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "environment": "string",
  • "enabled": true,
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Add a rule to a draft revision Deprecated

Deprecated. Use POST /v2/features/:id/revisions/:version/rules 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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
environment
required
string
required
object or object or object
object
object
revisionTitle
string
revisionComment
string
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "environment": "string",
  • "rule": {
    },
  • "rampSchedule": {
    },
  • "schedule": {
    },
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Update a rule in a draft revision Deprecated

Deprecated. Use PUT /v2/features/:id/revisions/:version/rules/:ruleId 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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
ruleId
required
string
Request Body schema: application/json
required
environment
required
string
required
object
object
object
revisionTitle
string
revisionComment
string
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "environment": "string",
  • "rule": {
    },
  • "rampSchedule": {
    },
  • "schedule": {
    },
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Delete a rule from a draft revision Deprecated

Deprecated. Use DELETE /v2/features/:id/revisions/:version/rules/:ruleId 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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
ruleId
required
string
Request Body schema: application/json
required
environment
required
string
revisionTitle
string
revisionComment
string
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "environment": "string",
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Reorder rules in an environment Deprecated

Deprecated. Use POST /v2/features/:id/revisions/:version/rules/reorder 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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
environment
required
string
ruleIds
required
Array of strings
revisionTitle
string
revisionComment
string
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "environment": "string",
  • "ruleIds": [
    ],
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Set ramp schedule for a rule Deprecated

Deprecated. Use PUT /v2/features/:id/revisions/:version/rules/:ruleId/ramp-schedule 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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
ruleId
required
string
Request Body schema: application/json
required
name
string
templateId
string
Array of objects
Array of objects
Array of objects
string or null

ISO 8601 date-time, e.g. "2025-06-01T00:00:00Z". Absent or null means start immediately on publish.

string or null

ISO 8601 date-time, e.g. "2025-07-01T00:00:00Z". The ramp ends at this time.

object
object
boolean or null
environment
string
Deprecated
revisionTitle
string
revisionComment
string
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "templateId": "string",
  • "startActions": [
    ],
  • "steps": [
    ],
  • "endActions": [
    ],
  • "startDate": "2019-08-24T14:15:22Z",
  • "cutoffDate": "2019-08-24T14:15:22Z",
  • "monitoringConfig": {
    },
  • "lockdownConfig": {
    },
  • "requiresStartApproval": true,
  • "environment": "string",
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Remove ramp schedule from a rule Deprecated

Deprecated. Use DELETE /v2/features/:id/revisions/:version/rules/:ruleId/ramp-schedule 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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
required
integer or "new" (string)
ruleId
required
string
Request Body schema: application/json
required
environment
string
Deprecated
revisionTitle
string
revisionComment
string
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "environment": "string",
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Request review for a draft revision Deprecated

Deprecated. Use POST /v2/features/:id/revisions/:version/request-review instead.

Moves the draft into the pending-review state and notifies reviewers.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
Request Body schema: application/json
required
comment
string
autoPublishOnApproval
boolean

Responses

Request samples

Content type
application/json
{
  • "comment": "string",
  • "autoPublishOnApproval": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Submit a review on a draft revision Deprecated

Deprecated. Use POST /v2/features/:id/revisions/:version/submit-review instead.

Submits an approve, request-changes, or comment review on the draft. 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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
Request Body schema: application/json
required
comment
string
action
string
Enum: "approve" "request-changes" "comment"
skipAutoPublish
boolean

Responses

Request samples

Content type
application/json
{
  • "comment": "string",
  • "action": "approve",
  • "skipAutoPublish": true
}

Response samples

Content type
application/json
{
  • "revision": {
    },
  • "autoPublished": true
}

Get merge status for a draft revision Deprecated

Deprecated. Use GET /v2/features/:id/revisions/:version/merge-status 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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/merge-status' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "success": true,
  • "liveVersion": 0,
  • "draftDateUpdated": "2019-08-24T14:15:22Z",
  • "conflicts": [
    ],
  • "rebaseRequired": true,
  • "result": {
    }
}

Rebase a draft revision onto the current live version Deprecated

Deprecated. Use POST /v2/features/:id/revisions/:version/rebase 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.<env>, metadata.<field>, rules.<ruleId>, rules.order, and the blanket rules (applies one strategy to all rule-level conflicts). Unrecognized keys are ignored; unresolved conflicts respond with 409.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
Request Body schema: application/json
required
object
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "conflictResolutions": {
    },
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Publish a draft revision Deprecated

Deprecated. Use POST /v2/features/:id/revisions/:version/publish instead.

Immediately publishes a draft revision, making it the live version of the feature. Blocked if the org requires approvals and bypassApprovalChecks is off.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
Request Body schema: application/json
required
comment
string
bypassApproval
boolean

Has no effect and is accepted only for backwards compatibility. Callers with the bypassApprovalChecks permission (or under the org-level REST bypass setting) bypass approval requirements automatically; all other callers must have the revision approved before publishing.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "comment": "string",
  • "bypassApproval": true,
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "revision": {
    },
  • "bypassedGates": [
    ]
}

Discard a draft revision Deprecated

Deprecated. Use POST /v2/features/:id/revisions/:version/discard instead.

Permanently discards a draft revision. Only drafts (never published revisions) can be discarded. Any pending ramp actions staged on the draft are dropped.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Revert the feature to a prior revision Deprecated

Deprecated. Use POST /v2/features/:id/revisions/:version/revert instead.

Creates a new draft (or immediately publishes) whose content matches the specified historical revision.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
version
required
integer
Request Body schema: application/json
required
strategy
string
Enum: "draft" "publish"
comment
string
title
string

Responses

Request samples

Content type
application/json
{
  • "strategy": "draft",
  • "comment": "string",
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Ramp Schedules

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.

Get all rampSchedules

Returns all ramp schedules for the organization, with optional filters.

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

featureId
string
status
string
Enum: "pending" "ready" "running" "paused" "completed" "rolled-back"

Filter by schedule status

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/ramp-schedules' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0,
  • "rampSchedules": [
    ]
}

Create a ramp schedule

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
name
string
featureId
string
ruleId
string
environment
string
Array of objects
Array of objects
Array of objects
string or null
string or null
boolean or null

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.

object or null
object
experimentHealthAction
string
Enum: "rollback" "hold" "warn"
templateId
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "featureId": "string",
  • "ruleId": "string",
  • "environment": "string",
  • "steps": [
    ],
  • "startActions": [
    ],
  • "endActions": [
    ],
  • "startDate": "2019-08-24T14:15:22Z",
  • "cutoffDate": "2019-08-24T14:15:22Z",
  • "requiresStartApproval": true,
  • "monitoringConfig": {
    },
  • "lockdownConfig": {
    },
  • "experimentHealthAction": "rollback",
  • "templateId": "string"
}

Response samples

Content type
application/json
{
  • "rampSchedule": {
    }
}

Start a ramp schedule

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X POST 'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/start' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "rampSchedule": {
    }
}

Pause a ramp schedule

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X POST 'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/pause' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "rampSchedule": {
    }
}

Resume a paused ramp schedule

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X POST 'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/resume' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "rampSchedule": {
    }
}

Roll back a ramp schedule

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
reason
string <= 200 characters

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "rampSchedule": {
    }
}

Restart a terminal ramp schedule

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X POST 'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/restart' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "rampSchedule": {
    }
}

Jump to a specific step

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
targetStepIndex
required
integer >= -1

Zero-based index of the step to jump to; -1 = pre-start

Responses

Request samples

Content type
application/json
{
  • "targetStepIndex": -1
}

Response samples

Content type
application/json
{
  • "rampSchedule": {
    }
}

Complete a ramp schedule immediately

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).

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
optional
disableRule
boolean

Responses

Request samples

Content type
application/json
{
  • "disableRule": true
}

Response samples

Content type
application/json
{
  • "rampSchedule": {
    }
}

Approve the pending approval gate

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X POST 'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/approve-step' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "rampSchedule": {
    }
}

Add a target rule to a ramp schedule

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
featureId
required
string
ruleId
required
string
environment
string
Deprecated

Deprecated pre-v2 disambiguator; ignored on v2 rules where rule.id is uniquely sufficient.

Responses

Request samples

Content type
application/json
{
  • "featureId": "string",
  • "ruleId": "string",
  • "environment": "string"
}

Response samples

Content type
application/json
{
  • "rampSchedule": {
    }
}

Remove a target rule from a ramp schedule

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
targetId
string

Target ID (from the targets array)

ruleId
string

Rule ID — use as an alternative to targetId

environment
string
Deprecated

Deprecated pre-v2 disambiguator. Optional when used with ruleId; omit on v2 ramps.

Responses

Request samples

Content type
application/json
{
  • "targetId": "string",
  • "ruleId": "string",
  • "environment": "string"
}

Response samples

Content type
application/json
{
  • "deleted": true,
  • "rampScheduleId": "string"
}

Advance to the next step, overriding any holds

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 canBypassApprovalChecks 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.
Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
optional
reason
string

Reason for advancing

force
boolean

Bypass a pending approval gate on the current step. Requires admin-level (canBypassApprovalChecks) permission. When omitted or false, a 409 is returned if the step has an unsatisfied holdConditions.requiresApproval gate.

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "force": true
}

Response samples

Content type
application/json
{
  • "rampSchedule": {
    }
}

Get ramp schedule status summary

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/ramp-schedules/{id}/status' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "string",
  • "currentStepIndex": 0,
  • "totalSteps": 0,
  • "lockdownMode": "string",
  • "startedAt": "string",
  • "lastRollbackAt": "string",
  • "lastRollbackReason": "string",
  • "monitoring": {
    },
  • "healthSummary": {
    }
}

Set ramp monitoring mode

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
monitoringMode
required
string
Enum: "auto" "manual"

auto schedules snapshots automatically while allowed by ramp state. manual disables agenda updates and relies on manual Update clicks.

Responses

Request samples

Content type
application/json
{
  • "monitoringMode": "auto"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "entityType": "feature",
  • "entityId": "string",
  • "targets": [
    ],
  • "startActions": [
    ],
  • "steps": [
    ],
  • "endActions": [
    ],
  • "startDate": "2019-08-24T14:15:22Z",
  • "cutoffDate": "2019-08-24T14:15:22Z",
  • "requiresStartApproval": true,
  • "startApprovedAt": "2019-08-24T14:15:22Z",
  • "status": "pending",
  • "currentStepIndex": -1,
  • "startedAt": "2019-08-24T14:15:22Z",
  • "phaseStartedAt": "2019-08-24T14:15:22Z",
  • "pausedAt": "2019-08-24T14:15:22Z",
  • "nextStepAt": "2019-08-24T14:15:22Z",
  • "nextProcessAt": "2019-08-24T14:15:22Z",
  • "elapsedMs": 0,
  • "lockdownConfig": {
    },
  • "monitoringConfig": {
    },
  • "experimentHealthAction": "rollback",
  • "currentStepEnteredAt": "2019-08-24T14:15:22Z",
  • "stepApproval": {
    },
  • "awaitingApproval": true,
  • "monitoringStartDate": "2019-08-24T14:15:22Z",
  • "lastRollbackAt": "2019-08-24T14:15:22Z",
  • "lastRollbackReason": "string",
  • "monitoringStatus": {
    }
}

Toggle automatic monitoring updates

Deprecated alias for setting monitoring mode. Prefer /actions/set-monitoring-mode.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
enabled
required
boolean

Legacy alias for monitoring mode (true => auto, false => manual).

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "entityType": "feature",
  • "entityId": "string",
  • "targets": [
    ],
  • "startActions": [
    ],
  • "steps": [
    ],
  • "endActions": [
    ],
  • "startDate": "2019-08-24T14:15:22Z",
  • "cutoffDate": "2019-08-24T14:15:22Z",
  • "requiresStartApproval": true,
  • "startApprovedAt": "2019-08-24T14:15:22Z",
  • "status": "pending",
  • "currentStepIndex": -1,
  • "startedAt": "2019-08-24T14:15:22Z",
  • "phaseStartedAt": "2019-08-24T14:15:22Z",
  • "pausedAt": "2019-08-24T14:15:22Z",
  • "nextStepAt": "2019-08-24T14:15:22Z",
  • "nextProcessAt": "2019-08-24T14:15:22Z",
  • "elapsedMs": 0,
  • "lockdownConfig": {
    },
  • "monitoringConfig": {
    },
  • "experimentHealthAction": "rollback",
  • "currentStepEnteredAt": "2019-08-24T14:15:22Z",
  • "stepApproval": {
    },
  • "awaitingApproval": true,
  • "monitoringStartDate": "2019-08-24T14:15:22Z",
  • "lastRollbackAt": "2019-08-24T14:15:22Z",
  • "lastRollbackReason": "string",
  • "monitoringStatus": {
    }
}

Update ramp monitoring configuration

Replaces the monitoring configuration. Metric IDs, snapshot cadence, and health-action thresholds (srmAction, noTrafficAction, etc.) can be updated at any time.

datasourceId and exposureQueryId are locked once monitoring starts — stop and recreate the schedule to change the data source.

Changes to guardrail or signal metric IDs take effect on the next analysis run.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
datasourceId
required
string
exposureQueryId
required
string
guardrailMetricIds
required
Array of strings non-empty
signalMetricIds
Array of strings
number or null
monitoringMode
string
Enum: "auto" "manual"
autoUpdate
boolean
srmAction
string
Enum: "rollback" "hold" "warn"
noTrafficAction
string
Enum: "rollback" "hold" "warn"
number or null

How long to wait for traffic before applying noTrafficAction. Defaults to 24 hours when null or not set.

multipleExposureAction
string
Enum: "rollback" "hold" "warn"

Responses

Request samples

Content type
application/json
{
  • "datasourceId": "string",
  • "exposureQueryId": "string",
  • "guardrailMetricIds": [
    ],
  • "signalMetricIds": [
    ],
  • "updateScheduleMinutes": 10,
  • "monitoringMode": "auto",
  • "autoUpdate": true,
  • "srmAction": "rollback",
  • "noTrafficAction": "rollback",
  • "noTrafficGracePeriodHours": 0,
  • "multipleExposureAction": "rollback"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "entityType": "feature",
  • "entityId": "string",
  • "targets": [
    ],
  • "startActions": [
    ],
  • "steps": [
    ],
  • "endActions": [
    ],
  • "startDate": "2019-08-24T14:15:22Z",
  • "cutoffDate": "2019-08-24T14:15:22Z",
  • "requiresStartApproval": true,
  • "startApprovedAt": "2019-08-24T14:15:22Z",
  • "status": "pending",
  • "currentStepIndex": -1,
  • "startedAt": "2019-08-24T14:15:22Z",
  • "phaseStartedAt": "2019-08-24T14:15:22Z",
  • "pausedAt": "2019-08-24T14:15:22Z",
  • "nextStepAt": "2019-08-24T14:15:22Z",
  • "nextProcessAt": "2019-08-24T14:15:22Z",
  • "elapsedMs": 0,
  • "lockdownConfig": {
    },
  • "monitoringConfig": {
    },
  • "experimentHealthAction": "rollback",
  • "currentStepEnteredAt": "2019-08-24T14:15:22Z",
  • "stepApproval": {
    },
  • "awaitingApproval": true,
  • "monitoringStartDate": "2019-08-24T14:15:22Z",
  • "lastRollbackAt": "2019-08-24T14:15:22Z",
  • "lastRollbackReason": "string",
  • "monitoringStatus": {
    }
}

Update ramp lockdown configuration

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
mode
required
string
Enum: "none" "locked"

Responses

Request samples

Content type
application/json
{
  • "mode": "none"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "entityType": "feature",
  • "entityId": "string",
  • "targets": [
    ],
  • "startActions": [
    ],
  • "steps": [
    ],
  • "endActions": [
    ],
  • "startDate": "2019-08-24T14:15:22Z",
  • "cutoffDate": "2019-08-24T14:15:22Z",
  • "requiresStartApproval": true,
  • "startApprovedAt": "2019-08-24T14:15:22Z",
  • "status": "pending",
  • "currentStepIndex": -1,
  • "startedAt": "2019-08-24T14:15:22Z",
  • "phaseStartedAt": "2019-08-24T14:15:22Z",
  • "pausedAt": "2019-08-24T14:15:22Z",
  • "nextStepAt": "2019-08-24T14:15:22Z",
  • "nextProcessAt": "2019-08-24T14:15:22Z",
  • "elapsedMs": 0,
  • "lockdownConfig": {
    },
  • "monitoringConfig": {
    },
  • "experimentHealthAction": "rollback",
  • "currentStepEnteredAt": "2019-08-24T14:15:22Z",
  • "stepApproval": {
    },
  • "awaitingApproval": true,
  • "monitoringStartDate": "2019-08-24T14:15:22Z",
  • "lastRollbackAt": "2019-08-24T14:15:22Z",
  • "lastRollbackReason": "string",
  • "monitoringStatus": {
    }
}

Update ramp schedule steps

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.

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
required
Array of objects

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.

Array
required
number or null

Hold duration in seconds before this step's gates are evaluated. null means no time gate.

monitored
boolean

When true, this step runs A/B traffic analysis while active. Applies only to future steps — cannot be changed on the currently executing step.

object

Additional gates that must clear before the step advances: minSampleSize and/or requiresApproval.

string or null

Optional notes shown to approvers when the step is awaiting approval.

Responses

Request samples

Content type
application/json
{
  • "steps": [
    ]
}

Response samples

Content type
application/json
{
  • "rampSchedule": {
    }
}

Trigger a manual monitoring update

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).

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X POST 'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/refresh-monitoring' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "rampSchedule": {
    }
}

Get a single rampSchedule

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/ramp-schedules/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "rampSchedule": {
    }
}

Delete a single rampSchedule

Permanently deletes a ramp schedule. This does not undo any rule patches that were already applied by completed steps.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/ramp-schedules/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "string"
}

Update a single rampSchedule

Updates the name, steps, endActions, startDate, or cutoffDate of a ramp schedule.

Only allowed when the schedule is in pending, ready, or paused status.

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).

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string
Array of objects
Array of objects
Array of objects
string or null
string or null
object or null
experimentHealthAction
string
Enum: "rollback" "hold" "warn"
object

When mode is 'locked', blocks all feature edits while the ramp is actively running.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "steps": [
    ],
  • "startActions": [
    ],
  • "endActions": [
    ],
  • "startDate": "2019-08-24T14:15:22Z",
  • "cutoffDate": "2019-08-24T14:15:22Z",
  • "monitoringConfig": {
    },
  • "experimentHealthAction": "rollback",
  • "lockdownConfig": {
    }
}

Response samples

Content type
application/json
{
  • "rampSchedule": {
    }
}

Data Sources

How GrowthBook connects and queries your data, including cached database schema metadata (information schemas) for tables and columns.

Get all data sources

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

projectId
string

Filter by project id

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/data-sources' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "dataSources": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Get a single data source

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/data-sources/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "dataSource": {
    }
}

Get a Data Source's Information Schema

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
dataSourceId
required
string

The id of the data source

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/data-sources/{dataSourceId}/information-schema' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "informationSchema": {
    }
}

Get a single Information Schema Table by id

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
tableId
required
string

The id of the information schema table

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/information-schema-tables/{tableId}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "informationSchemaTable": {
    }
}

Fact Tables

Fact Tables describe the shape of your data warehouse tables

Get all fact tables

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

datasourceId
string

Filter by Data Source

projectId
string

Filter by project id

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/fact-tables' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "factTables": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a single fact table

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
name
required
string
description
string <= 10000 characters

Description of the fact table

owner
string

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.

projects
Array of strings

List of associated project ids

tags
Array of strings

List of associated tags

datasource
required
string

The datasource id

userIdTypes
required
Array of strings

List of identifier columns in this table. For example, "id" or "anonymous_id"

object

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.

sql
required
string

The SQL query for this fact table

eventName
string

The event name used in SQL template variables

Array of objects (FactTableColumnInput)

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.

managedBy
string
Enum: "" "api" "admin"

Set this to "api" to disable editing in the GrowthBook UI

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "owner": "string",
  • "projects": [
    ],
  • "tags": [
    ],
  • "datasource": "string",
  • "userIdTypes": [
    ],
  • "aggregatedFactTableSettings": {
    },
  • "sql": "string",
  • "eventName": "string",
  • "columns": [
    ],
  • "managedBy": ""
}

Response samples

Content type
application/json
{
  • "factTable": {
    }
}

Get a single fact table

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/fact-tables/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "factTable": {
    }
}

Update a single fact table

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
name
string
description
string <= 10000 characters

Description of the fact table

owner
string

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.

projects
Array of strings

List of associated project ids

tags
Array of strings

List of associated tags

userIdTypes
Array of strings

List of identifier columns in this table. For example, "id" or "anonymous_id"

object

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.

sql
string

The SQL query for this fact table

eventName
string

The event name used in SQL template variables

Array of objects (FactTableColumnInput)

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.

string or null

Error message if there was an issue parsing the SQL schema

managedBy
string
Enum: "" "api" "admin"

Set this to "api" to disable editing in the GrowthBook UI

archived
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "owner": "string",
  • "projects": [
    ],
  • "tags": [
    ],
  • "userIdTypes": [
    ],
  • "aggregatedFactTableSettings": {
    },
  • "sql": "string",
  • "eventName": "string",
  • "columns": [
    ],
  • "columnsError": "string",
  • "managedBy": "",
  • "archived": true
}

Response samples

Content type
application/json
{
  • "factTable": {
    }
}

Deletes a single fact table

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/fact-tables/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "ftb_123abc"
}

Get all filters for a fact table

Authorizations:
bearerAuthbasicAuth
path Parameters
factTableId
required
string

Specify a specific fact table

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/fact-tables/abc123/filters' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "factTableFilters": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a single fact table filter

Authorizations:
bearerAuthbasicAuth
path Parameters
factTableId
required
string

Specify a specific fact table

Request Body schema: application/json
required
name
required
string
description
string <= 10000 characters

Description of the fact table filter

value
required
string

The SQL expression for this filter.

managedBy
string
Enum: "" "api"

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"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "value": "country = 'US'",
  • "managedBy": ""
}

Response samples

Content type
application/json
{
  • "factTableFilter": {
    }
}

Get a single fact filter

Authorizations:
bearerAuthbasicAuth
path Parameters
factTableId
required
string

Specify a specific fact table

id
required
string

The id of the requested resource

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/fact-tables/abc123/filters/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "factTableFilter": {
    }
}

Update a single fact table filter

Authorizations:
bearerAuthbasicAuth
path Parameters
factTableId
required
string

Specify a specific fact table

id
required
string

The id of the requested resource

Request Body schema: application/json
required
name
string
description
string <= 10000 characters

Description of the fact table filter

value
string

The SQL expression for this filter.

managedBy
string
Enum: "" "api"

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"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "value": "country = 'US'",
  • "managedBy": ""
}

Response samples

Content type
application/json
{
  • "factTableFilter": {
    }
}

Deletes a single fact table filter

Authorizations:
bearerAuthbasicAuth
path Parameters
factTableId
required
string

Specify a specific fact table

id
required
string

The id of the requested resource

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/fact-tables/abc123/filters/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "flt_123abc"
}

Get the materialization status of a fact table's shared daily aggregated tables

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/fact-tables/abc123/aggregated-tables' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "aggregatedFactTables": [
    ],
  • "nextScheduledUpdate": "2019-08-24T14:15:22Z"
}

Force a refresh or full restate of a fact table's shared daily aggregated tables

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
idType
string

Limit the refresh to a single id type. If omitted, all of the fact table's aggregatedFactTableSettings.idTypes are refreshed.

fullRestate
boolean

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).

Responses

Request samples

Content type
application/json
{
  • "idType": "string",
  • "fullRestate": true
}

Response samples

Content type
application/json
{
  • "runs": [
    ]
}

List aggregated table runs

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

query Parameters
idType
string

Only return runs for this id type. When omitted, runs for all id types are returned.

limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

Responses

Request samples 

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'

Response samples

Content type
application/json
{
  • "runs": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Get a single aggregated table run

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the fact table

runId
required
string

The id of the aggregated table run (e.g. aftr_...)

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/fact-tables/abc123/aggregated-tables/runs/aftr_abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "run": {
    }
}

Bulk import fact tables, filters, and metrics

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
Array of objects
Array of objects
Array of objects

Responses

Request samples

Content type
application/json
{
  • "factTables": [
    ],
  • "factTableFilters": [
    ],
  • "factMetrics": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "factTablesAdded": 0,
  • "factTablesUpdated": 0,
  • "factTableFiltersAdded": 0,
  • "factTableFiltersUpdated": 0,
  • "factMetricsAdded": 0,
  • "factMetricsUpdated": 0
}

Fact Metrics

Fact Metrics are metrics built on top of Fact Table definitions

Get all fact metrics

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

datasourceId
string

Filter by Data Source

projectId
string

Filter by project id

factTableId
string

Filter by Fact Table Id (for ratio metrics, we only look at the numerator)

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/fact-metrics' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "factMetrics": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a single fact metric

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
name
required
string
description
string <= 10000 characters
owner
string

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.

projects
Array of strings
tags
Array of strings
metricType
required
string
Enum: "proportion" "retention" "mean" "quantile" "ratio" "dailyParticipation"
required
object
object

Only when metricType is 'ratio'

inverse
boolean

Set to true for things like Bounce Rate, where you want the metric to decrease

object

Controls the settings for quantile metrics (mandatory if metricType is "quantile")

object

Controls how outliers are handled

object

Controls the conversion window for the metric

object

Controls the bayesian prior for the metric. If omitted, organization defaults will be used.

object

Controls the regression adjustment (CUPED) settings for the metric

riskThresholdSuccess
number >= 0
Deprecated

No longer used. Threshold for Risk to be considered low enough, as a proportion (e.g. put 0.0025 for 0.25%).
Must be a non-negative number and must not be higher than riskThresholdDanger.

riskThresholdDanger
number >= 0
Deprecated

No longer used. Threshold for Risk to be considered too high, as a proportion (e.g. put 0.0125 for 1.25%).
Must be a non-negative number.

displayAsPercentage
boolean

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.

minPercentChange
number >= 0

Minimum percent change to consider uplift significant, as a proportion (e.g. put 0.005 for 0.5%)

maxPercentChange
number >= 0

Maximum percent change to consider uplift significant, as a proportion (e.g. put 0.5 for 50%)

minSampleSize
number >= 0
targetMDE
number >= 0

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.

managedBy
string
Enum: "" "api" "admin"

Set this to "api" to disable editing in the GrowthBook UI

metricAutoSlices
Array of strings

Array of slice column names that will be automatically included in metric analysis. This is an enterprise feature.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "owner": "string",
  • "projects": [
    ],
  • "tags": [
    ],
  • "metricType": "proportion",
  • "numerator": {
    },
  • "denominator": {
    },
  • "inverse": true,
  • "quantileSettings": {
    },
  • "cappingSettings": {
    },
  • "windowSettings": {
    },
  • "priorSettings": {
    },
  • "regressionAdjustmentSettings": {
    },
  • "riskThresholdSuccess": 0,
  • "riskThresholdDanger": 0,
  • "displayAsPercentage": true,
  • "minPercentChange": 0,
  • "maxPercentChange": 0,
  • "minSampleSize": 0,
  • "targetMDE": 0,
  • "managedBy": "",
  • "metricAutoSlices": [
    ]
}

Response samples

Content type
application/json
{
  • "factMetric": {
    }
}

Get a single fact metric

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/fact-metrics/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "factMetric": {
    }
}

Update a single fact metric

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
name
string
description
string <= 10000 characters
owner
string

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.

projects
Array of strings
tags
Array of strings
metricType
string
Enum: "proportion" "retention" "mean" "quantile" "ratio" "dailyParticipation"
object
object

Only when metricType is 'ratio'

inverse
boolean

Set to true for things like Bounce Rate, where you want the metric to decrease

object

Controls the settings for quantile metrics (mandatory if metricType is "quantile")

object

Controls how outliers are handled

object

Controls the conversion window for the metric

object

Controls the bayesian prior for the metric. If omitted, organization defaults will be used.

object

Controls the regression adjustment (CUPED) settings for the metric

riskThresholdSuccess
number >= 0
Deprecated

No longer used. Threshold for Risk to be considered low enough, as a proportion (e.g. put 0.0025 for 0.25%).
Must be a non-negative number and must not be higher than riskThresholdDanger.

riskThresholdDanger
number >= 0
Deprecated

No longer used. Threshold for Risk to be considered too high, as a proportion (e.g. put 0.0125 for 1.25%).
Must be a non-negative number.

displayAsPercentage
boolean

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.

minPercentChange
number >= 0

Minimum percent change to consider uplift significant, as a proportion (e.g. put 0.005 for 0.5%)

maxPercentChange
number >= 0

Maximum percent change to consider uplift significant, as a proportion (e.g. put 0.5 for 50%)

minSampleSize
number >= 0
targetMDE
number >= 0
managedBy
string
Enum: "" "api" "admin"

Set this to "api" to disable editing in the GrowthBook UI

archived
boolean
metricAutoSlices
Array of strings

Array of slice column names that will be automatically included in metric analysis. This is an enterprise feature.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "owner": "string",
  • "projects": [
    ],
  • "tags": [
    ],
  • "metricType": "proportion",
  • "numerator": {
    },
  • "denominator": {
    },
  • "inverse": true,
  • "quantileSettings": {
    },
  • "cappingSettings": {
    },
  • "windowSettings": {
    },
  • "priorSettings": {
    },
  • "regressionAdjustmentSettings": {
    },
  • "riskThresholdSuccess": 0,
  • "riskThresholdDanger": 0,
  • "displayAsPercentage": true,
  • "minPercentChange": 0,
  • "maxPercentChange": 0,
  • "minSampleSize": 0,
  • "targetMDE": 0,
  • "managedBy": "",
  • "archived": true,
  • "metricAutoSlices": [
    ]
}

Response samples

Content type
application/json
{
  • "factMetric": {
    }
}

Deletes a single fact metric

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/fact-metrics/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "fact__123abc"
}

Create a fact metric analysis

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The fact metric id to analyze

Request Body schema: application/json
optional
userIdType
string

The identifier type to use for the analysis. If not provided, defaults to the first available identifier type in the fact table.

lookbackDays
number [ 1 .. 999999 ]

Number of days to look back for the analysis. Defaults to 30.

populationType
string
Enum: "factTable" "segment"

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.

string or null

The ID of the population (e.g., segment ID) when populationType is not 'factTable'. Defaults to null.

additionalNumeratorFilters
Array of strings

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.

additionalDenominatorFilters
Array of strings

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.

useCache
boolean

Whether to use a cached query if one exists. Defaults to true.

Responses

Request samples

Content type
application/json
{
  • "userIdType": "string",
  • "lookbackDays": 1,
  • "populationType": "factTable",
  • "populationId": "string",
  • "additionalNumeratorFilters": [
    ],
  • "additionalDenominatorFilters": [
    ],
  • "useCache": true
}

Response samples

Content type
application/json
{
  • "metricAnalysis": {
    }
}

Metrics (legacy)

Metrics used as goals and guardrails for experiments

Get all metrics

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

projectId
string

Filter by project id

datasourceId
string

Filter by Data Source

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/metrics' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "metrics": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a single metric

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
datasourceId
required
string

ID for the DataSource

managedBy
string
Enum: "" "api"

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.

owner
string

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.

name
required
string

Name of the metric

description
string <= 10000 characters

Description of the metric

type
required
string
Enum: "binomial" "count" "duration" "revenue"

Type of metric. See Metrics documentation

tags
Array of strings

List of tags

projects
Array of strings

List of project IDs for projects that can access this metric

archived
boolean
object
object

Preferred way to define SQL. Only one of sql, sqlBuilder or mixpanel allowed, and at least one must be specified.

object

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.

object

Only use for MixPanel (non-SQL) Data Sources. Only one of sql, sqlBuilder or mixpanel allowed, and at least one must be specified.

Responses

Request samples

Content type
application/json
{
  • "datasourceId": "string",
  • "managedBy": "",
  • "owner": "string",
  • "name": "string",
  • "description": "string",
  • "type": "binomial",
  • "tags": [
    ],
  • "projects": [
    ],
  • "archived": true,
  • "behavior": {
    },
  • "sql": {
    },
  • "sqlBuilder": {
    },
  • "mixpanel": {
    }
}

Response samples

Content type
application/json
{
  • "metric": {
    }
}

Get a single metric

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/metrics/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "metric": {
    }
}

Update a metric

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
managedBy
string
Enum: "" "api" "admin"

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.

owner
string

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.

name
string

Name of the metric

description
string <= 10000 characters

Description of the metric

type
string
Enum: "binomial" "count" "duration" "revenue"

Type of metric. See Metrics documentation

tags
Array of strings

List of tags

projects
Array of strings

List of project IDs for projects that can access this metric

archived
boolean
object
object

Preferred way to define SQL. Only one of sql, sqlBuilder or mixpanel allowed.

object

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

object

Only use for MixPanel (non-SQL) Data Sources. Only one of sql, sqlBuilder or mixpanel allowed.

Responses

Request samples

Content type
application/json
{
  • "managedBy": "",
  • "owner": "string",
  • "name": "string",
  • "description": "string",
  • "type": "binomial",
  • "tags": [
    ],
  • "projects": [
    ],
  • "archived": true,
  • "behavior": {
    },
  • "sql": {
    },
  • "sqlBuilder": {
    },
  • "mixpanel": {
    }
}

Response samples

Content type
application/json
{
  • "updatedId": "string"
}

Deletes a metric

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/metrics/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "string"
}

Get results for all experiments that use a metric

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

q
string

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

projectId
string

Filter by comma-separated project ids or names

owner
string

Filter by comma-separated owner ids, names, or emails

status
string

Filter by comma-separated statuses (draft, running, stopped)

result
string

Filter by comma-separated results (won, lost, inconclusive, dnf)

tag
string

Filter by comma-separated tags

type
string

Filter by comma-separated experiment types (feature, visualChange, redirect)

bandits
string
Enum: "true" "false"

When true, return only multi-armed bandits; when false, exclude them

startDate
string

Only include experiments that have a phase which ended on or after this date

endDate
string

Only include experiments that have a phase which ended on or before this date

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/metrics/met_abc123/experiments' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "experimentResults": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Experiments

Experiments (A/B Tests)

Get all experiments

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

projectId
string

Filter by project id

datasourceId
string

Filter by Data Source

trackingKey
string

Filter by experiment tracking key

experimentId
string
Deprecated

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.

status
string
Enum: "draft" "running" "stopped"
q
string

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

owner
string

Filter by comma-separated owner ids, names, or emails

result
Array of strings
Items Enum: "dnf" "won" "lost" "inconclusive"

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

tag
string

Filter by comma-separated tags

implementationType
Array of strings
Items Enum: "feature" "visualChange" "redirect"

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

metricId
string

Filter by comma-separated metric ids. Matches experiments that use a metric as a goal, secondary, or guardrail metric

bandits
string
Enum: "true" "false"

When true, return only multi-armed bandits; when false, exclude them

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean

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.

sortBy
string
Default: "dateCreated"
Enum: "dateCreated" "dateUpdated" "name"

Field to sort the results by

sortOrder
string
Default: "asc"
Enum: "asc" "desc"

Sort direction (used with sortBy)

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/experiments' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "experiments": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a single experiment

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
datasourceId
string

ID for the DataSource. Can only be set if a templateId is not provided.

assignmentQueryId
string

The ID property of one of the assignment query objects associated with the datasource. Can only be set if a templateId is not provided.

trackingKey
required
string
bypassDuplicateKeyCheck
boolean

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.

name
required
string

Name of the experiment

type
string
Enum: "standard" "multi-armed-bandit"
project
string

Project ID which the experiment belongs to

templateId
string

ID of the ExperimentTemplate this experiment was created from. Template fields are applied by default and overridden by explicitly provided payload fields.

hypothesis
string

Hypothesis of the experiment

description
string <= 10000 characters

Description of the experiment

tags
Array of strings
metrics
Array of strings
secondaryMetrics
Array of strings
guardrailMetrics
Array of strings
activationMetric
string

Users must convert on this metric before being included

segmentId
string

Only users in this segment will be included

queryFilter
string

WHERE clause to add to the default experiment query

owner
string

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 user associated with the request's Personal Access Token (PAT), if one is being used.

archived
boolean
status
string
Enum: "draft" "running" "stopped"
autoRefresh
boolean
hashAttribute
string
fallbackAttribute
string
1 (number) or 2 (number)
disableStickyBucketing
boolean
bucketVersion
number
minBucketVersion
number
releasedVariationId
string
excludeFromPayload
boolean
inProgressConversions
string
Enum: "loose" "strict"
attributionModel
string
Enum: "firstExposure" "experimentDuration" "lookbackOverride"

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.

object

Controls the lookback override for the experiment. For type "window", value must be a non-negative number and valueUnit is required.

statsEngine
string
Enum: "bayesian" "frequentist"
required
Array of objects >= 2 items
Array of objects
regressionAdjustmentEnabled
boolean

Controls whether regression adjustment (CUPED) is enabled for experiment analyses

sequentialTestingEnabled
boolean

Only applicable to frequentist analyses

sequentialTestingTuningParameter
number
shareLevel
string
Enum: "public" "organization"
banditScheduleValue
number
banditScheduleUnit
string
Enum: "days" "hours"
banditBurnInValue
number
banditBurnInUnit
string
Enum: "days" "hours"
banditConversionWindowValue
number
banditConversionWindowUnit
string
Enum: "days" "hours"
boolean or null

When null, the organization default is used.

object

Controls the decision framework and metric overrides for the experiment. Replaces the entire stored object on update (does not patch individual fields).

Array of objects

Per-metric analysis overrides for this experiment. Replaces the entire stored array (does not patch individual entries).

defaultDashboardId
string

ID of the default dashboard for this experiment.

object
Array of objects

Custom slices that apply to ALL applicable metrics in the experiment

precomputedUnitDimensionIds
Array of strings <= 3 items
object

Schedule a future start for a draft experiment. Only startAt is currently supported.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "datasourceId": "string",
  • "assignmentQueryId": "string",
  • "trackingKey": "string",
  • "bypassDuplicateKeyCheck": true,
  • "name": "string",
  • "type": "standard",
  • "project": "string",
  • "templateId": "string",
  • "hypothesis": "string",
  • "description": "string",
  • "tags": [
    ],
  • "metrics": [
    ],
  • "secondaryMetrics": [
    ],
  • "guardrailMetrics": [
    ],
  • "activationMetric": "string",
  • "segmentId": "string",
  • "queryFilter": "string",
  • "owner": "string",
  • "archived": true,
  • "status": "draft",
  • "autoRefresh": true,
  • "hashAttribute": "string",
  • "fallbackAttribute": "string",
  • "hashVersion": 1,
  • "disableStickyBucketing": true,
  • "bucketVersion": 0,
  • "minBucketVersion": 0,
  • "releasedVariationId": "string",
  • "excludeFromPayload": true,
  • "inProgressConversions": "loose",
  • "attributionModel": "firstExposure",
  • "lookbackOverride": {
    },
  • "statsEngine": "bayesian",
  • "variations": [
    ],
  • "phases": [
    ],
  • "regressionAdjustmentEnabled": true,
  • "sequentialTestingEnabled": true,
  • "sequentialTestingTuningParameter": 0,
  • "shareLevel": "public",
  • "banditScheduleValue": 0,
  • "banditScheduleUnit": "days",
  • "banditBurnInValue": 0,
  • "banditBurnInUnit": "days",
  • "banditConversionWindowValue": 0,
  • "banditConversionWindowUnit": "days",
  • "postStratificationEnabled": true,
  • "decisionFrameworkSettings": {
    },
  • "metricOverrides": [
    ],
  • "defaultDashboardId": "string",
  • "customFields": {
    },
  • "customMetricSlices": [
    ],
  • "precomputedUnitDimensionIds": [
    ],
  • "statusUpdateSchedule": {
    },
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "experiment": {
    }
}

Get latest results for many experiments

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.

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

projectId
string

Filter by project id

datasourceId
string

Filter by Data Source

trackingKey
string

Filter by experiment tracking key

status
string
Enum: "draft" "running" "stopped"

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/experiments/results' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "experimentResults": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Get a single experiment

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/experiments/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "experiment": {
    }
}

Update a single experiment

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
datasourceId
string

Can only be set if existing experiment does not have a datasource

assignmentQueryId
string
trackingKey
string
bypassDuplicateKeyCheck
boolean

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.

name
string

Name of the experiment

type
string
Enum: "standard" "multi-armed-bandit"
project
string

Project ID which the experiment belongs to

hypothesis
string

Hypothesis of the experiment

description
string <= 10000 characters

Description of the experiment

tags
Array of strings
metrics
Array of strings
secondaryMetrics
Array of strings
guardrailMetrics
Array of strings
activationMetric
string

Users must convert on this metric before being included

segmentId
string

Only users in this segment will be included

queryFilter
string

WHERE clause to add to the default experiment query

owner
string

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.

archived
boolean
status
string
Enum: "draft" "running" "stopped"
autoRefresh
boolean
hashAttribute
string
fallbackAttribute
string
1 (number) or 2 (number)
disableStickyBucketing
boolean
bucketVersion
number
minBucketVersion
number
results
string
Enum: "dnf" "won" "lost" "inconclusive"

The result status of the experiment. Maps to resultSummary.status in the GET response.

winner
number

The index of the winning variation (0-indexed). Maps to resultSummary.winner (variation ID) in the GET response.

analysis
string

Analysis summary or conclusions for the experiment. Maps to resultSummary.conclusions in the GET response.

releasedVariationId
string

The ID of the released variation. Maps to resultSummary.releasedVariationId in the GET response.

excludeFromPayload
boolean

If true, the experiment is excluded from the SDK payload. Maps to resultSummary.excludeFromPayload in the GET response.

inProgressConversions
string
Enum: "loose" "strict"
attributionModel
string
Enum: "firstExposure" "experimentDuration" "lookbackOverride"

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.

object

Controls the lookback override for the experiment. For type "window", value must be a non-negative number and valueUnit is required.

statsEngine
string
Enum: "bayesian" "frequentist"
Array of objects >= 2 items
Array of objects
regressionAdjustmentEnabled
boolean

Controls whether regression adjustment (CUPED) is enabled for experiment analyses

sequentialTestingEnabled
boolean

Only applicable to frequentist analyses

sequentialTestingTuningParameter
number
shareLevel
string
Enum: "public" "organization"
banditScheduleValue
number
banditScheduleUnit
string
Enum: "days" "hours"
banditBurnInValue
number
banditBurnInUnit
string
Enum: "days" "hours"
banditConversionWindowValue
number
banditConversionWindowUnit
string
Enum: "days" "hours"
boolean or null

When null, the organization default is used.

object

Controls the decision framework and metric overrides for the experiment. Replaces the entire stored object on update (does not patch individual fields).

Array of objects

Per-metric analysis overrides for this experiment. Replaces the entire stored array (does not patch individual entries).

defaultDashboardId
string

ID of the default dashboard for this experiment.

object
Array of objects

Custom slices that apply to ALL applicable metrics in the experiment

object or null
precomputedUnitDimensionIds
Array of strings <= 3 items
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "datasourceId": "string",
  • "assignmentQueryId": "string",
  • "trackingKey": "string",
  • "bypassDuplicateKeyCheck": true,
  • "name": "string",
  • "type": "standard",
  • "project": "string",
  • "hypothesis": "string",
  • "description": "string",
  • "tags": [
    ],
  • "metrics": [
    ],
  • "secondaryMetrics": [
    ],
  • "guardrailMetrics": [
    ],
  • "activationMetric": "string",
  • "segmentId": "string",
  • "queryFilter": "string",
  • "owner": "string",
  • "archived": true,
  • "status": "draft",
  • "autoRefresh": true,
  • "hashAttribute": "string",
  • "fallbackAttribute": "string",
  • "hashVersion": 1,
  • "disableStickyBucketing": true,
  • "bucketVersion": 0,
  • "minBucketVersion": 0,
  • "results": "dnf",
  • "winner": 0,
  • "analysis": "string",
  • "releasedVariationId": "string",
  • "excludeFromPayload": true,
  • "inProgressConversions": "loose",
  • "attributionModel": "firstExposure",
  • "lookbackOverride": {
    },
  • "statsEngine": "bayesian",
  • "variations": [
    ],
  • "phases": [
    ],
  • "regressionAdjustmentEnabled": true,
  • "sequentialTestingEnabled": true,
  • "sequentialTestingTuningParameter": 0,
  • "shareLevel": "public",
  • "banditScheduleValue": 0,
  • "banditScheduleUnit": "days",
  • "banditBurnInValue": 0,
  • "banditBurnInUnit": "days",
  • "banditConversionWindowValue": 0,
  • "banditConversionWindowUnit": "days",
  • "postStratificationEnabled": true,
  • "decisionFrameworkSettings": {
    },
  • "metricOverrides": [
    ],
  • "defaultDashboardId": "string",
  • "customFields": {
    },
  • "customMetricSlices": [
    ],
  • "statusUpdateSchedule": {
    },
  • "precomputedUnitDimensionIds": [
    ],
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "experiment": {
    }
}

Get an experiment pre-launch checklist status

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/experiments/exp_abc123/start-checklist' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "checklistItems": [
    ],
  • "status": "ready"
}

Get results for an experiment

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

query Parameters
phase
string
dimension
string

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/experiments/{id}/results' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "experiment": {
    },
  • "result": {
    }
}

Start/Stage an experiment

Starts an experiment or stages it for a future start if a statusUpdateSchedule is set on the experiment.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
optional
skipChecklist
boolean

If true, skips validating the experiment satisifies all pre-launch checklist items

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "skipChecklist": true,
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "experiment": {
    },
  • "message": "string"
}

Mark manual pre-launch checklist items complete

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
keys
required
Array of strings non-empty

Manual pre-launch checklist item keys to mark as complete (auto-computed items cannot be updated via this endpoint).

Responses

Request samples

Content type
application/json
{
  • "keys": [
    ]
}

Response samples

Content type
application/json
{
  • "checklistItems": [
    ],
  • "status": "ready"
}

Stop an experiment

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
results
required
string
Enum: "dnf" "won" "lost" "inconclusive"

The experiment conclusion status.

enableTemporaryRollout
boolean

If true, include this stopped experiment in SDK payload and force the release variation (releasedVariationId) to all traffic.

releasedVariationId
string

Required if enableTemporaryRollout is true. Variation ID (e.g. var_abc123) to release to 100% of traffic eligible for this experiment.

winnerVariationId
string

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.

analysis
string

Optional markdown summary displayed on the experiment results page.

reason
string

Optional reason for ending the phase stored on the latest phase metadata.

dateEnded
string

Optional ISO datetime for ending the latest phase. Defaults to the current date and time.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "results": "dnf",
  • "enableTemporaryRollout": true,
  • "releasedVariationId": "string",
  • "winnerVariationId": "string",
  • "analysis": "string",
  • "reason": "string",
  • "dateEnded": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "experiment": {
    }
}

Modify temporary rollout status for a stopped experiment

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
enableTemporaryRollout
required
boolean

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.

releasedVariationId
string

Variation ID (e.g. var_abc123) to release to 100% of traffic eligible for this experiment. Required if enableTemporaryRollout is true.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "enableTemporaryRollout": true,
  • "releasedVariationId": "string",
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "experiment": {
    }
}

Create Experiment Snapshot

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The experiment id of the experiment to update

Request Body schema: application/json
optional
triggeredBy
string
Enum: "manual" "schedule"

Set to "schedule" if you want this request to trigger notifications and other events as it if were a scheduled update. Defaults to manual.

dimension
string

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". Omit this field to create a standard snapshot.

phase
integer >= 0

Zero-based phase index to snapshot, where 0 is the first experiment phase. Defaults to the latest phase.

Responses

Request samples

Content type
application/json
{
  • "triggeredBy": "manual",
  • "dimension": "string",
  • "phase": 0
}

Response samples

Content type
application/json
{
  • "snapshot": {
    }
}

Upload a variation screenshot

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
variationId
required
string
Request Body schema: application/json
required
screenshot
required
string <base64>

Base64-encoded screenshot data

contentType
required
string
Enum: "image/png" "image/jpeg" "image/gif"

MIME type of the screenshot

description
string

Optional description for the screenshot

Responses

Request samples

Content type
application/json
{
  • "screenshot": "string",
  • "contentType": "image/png",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "screenshot": {
    }
}

Delete a variation screenshot

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
variationId
required
string
Request Body schema: application/json
required
path
required
string

The screenshot path/URL to delete (from upload response)

Responses

Request samples

Content type
application/json
{
  • "path": "string"
}

Response samples

Content type
application/json
{ }

Get a list of experiments with names and ids

Authorizations:
bearerAuthbasicAuth
query Parameters
projectId
string

Filter by project id

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/experiment-names' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "experiments": [
    ]
}

Namespaces

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.

Get all namespaces

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/namespaces' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "namespaces": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a namespace

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
displayName
required
string

Human-readable display name. Must be unique within the organization.

description
string
status
string
Enum: "active" "inactive"
format
string
Enum: "legacy" "multiRange"

Namespace format. Defaults to 'multiRange', which supports multiple ranges per experiment and a configurable hash attribute.

hashAttribute
string

Required when format is 'multiRange'. The user attribute (e.g. 'id', 'device_id') used to assign users to namespace buckets.

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "description": "string",
  • "status": "active",
  • "format": "legacy",
  • "hashAttribute": "string"
}

Response samples

Content type
application/json
{
  • "namespace": {
    }
}

Get a single namespace

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The unique id of the namespace

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/namespaces/ns-abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "namespace": {
    }
}

Update a namespace

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The unique id of the namespace

Request Body schema: application/json
required
displayName
string

Human-readable display name.

description
string

Namespace description.

status
string
Enum: "active" "inactive"

Set to 'inactive' to disable the namespace.

hashAttribute
string

Only applies to multiRange namespaces. Changes which user attribute is used for bucket hashing going forward.

Responses

Request samples

Content type
application/json
{
  • "displayName": "string",
  • "description": "string",
  • "status": "active",
  • "hashAttribute": "string"
}

Response samples

Content type
application/json
{
  • "namespace": {
    }
}

Delete a namespace

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The unique id of the namespace

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/namespaces/ns-abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "ns-abc123"
}

Get namespace membership

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The unique id of the namespace

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/namespaces/ns-abc123/memberships' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "experiments": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Rotate namespace seed

⚠️ 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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The unique id of the namespace

Request Body schema: application/json
required
seed
string

A specific value to use as the new seed. If omitted, a random value is generated.

Responses

Request samples

Content type
application/json
{
  • "seed": "string"
}

Response samples

Content type
application/json
{
  • "namespace": {
    }
}

Experiment Snapshots

Experiment Snapshots (the individual updates of an experiment)

Create Experiment Snapshot

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The experiment id of the experiment to update

Request Body schema: application/json
optional
triggeredBy
string
Enum: "manual" "schedule"

Set to "schedule" if you want this request to trigger notifications and other events as it if were a scheduled update. Defaults to manual.

dimension
string

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". Omit this field to create a standard snapshot.

phase
integer >= 0

Zero-based phase index to snapshot, where 0 is the first experiment phase. Defaults to the latest phase.

Responses

Request samples

Content type
application/json
{
  • "triggeredBy": "manual",
  • "dimension": "string",
  • "phase": 0
}

Response samples

Content type
application/json
{
  • "snapshot": {
    }
}

Get an experiment snapshot status

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource (a snapshot ID, not experiment ID)

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/snapshots/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "snapshot": {
    }
}

Dimensions

Dimensions used during experiment analysis

Get all dimensions

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

datasourceId
string

Filter by Data Source

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/dimensions' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "dimensions": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a single dimension

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
name
required
string

Name of the dimension

description
string <= 10000 characters

Description of the dimension

owner
string

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.

datasourceId
required
string

ID of the datasource this dimension belongs to

identifierType
required
string

Type of identifier (user, anonymous, etc.)

query
required
string

SQL query or equivalent for the dimension

managedBy
string
Enum: "" "api"

Where this dimension must be managed from. If not set (empty string), it can be managed from anywhere.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "owner": "string",
  • "datasourceId": "string",
  • "identifierType": "string",
  • "query": "string",
  • "managedBy": ""
}

Response samples

Content type
application/json
{
  • "dimension": {
    }
}

Get a single dimension

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/dimensions/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "dimension": {
    }
}

Update a single dimension

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
name
string

Name of the dimension

description
string <= 10000 characters

Description of the dimension

owner
string

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.

datasourceId
string

ID of the datasource this dimension belongs to

identifierType
string

Type of identifier (user, anonymous, etc.)

query
string

SQL query or equivalent for the dimension

managedBy
string
Enum: "" "api"

Where this dimension must be managed from. If not set (empty string), it can be managed from anywhere.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "owner": "string",
  • "datasourceId": "string",
  • "identifierType": "string",
  • "query": "string",
  • "managedBy": ""
}

Response samples

Content type
application/json
{
  • "dimension": {
    }
}

Deletes a single dimension

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/dimensions/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "dim_123abc"
}

Segments

Segments used during experiment analysis

Get all segments

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

datasourceId
string

Filter by Data Source

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/segments' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "segments": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a single segment

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
name
required
string

Name of the segment

owner
string

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.

description
string <= 10000 characters

Description of the segment

datasourceId
required
string

ID of the datasource this segment belongs to

identifierType
required
string

Type of identifier (user, anonymous, etc.)

projects
Array of strings

List of project IDs for projects that can access this segment

managedBy
string
Enum: "" "api"

Where this Segment must be managed from. If not set (empty string), it can be managed from anywhere.

type
required
string
Enum: "SQL" "FACT"

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.

query
string

SQL query that defines the Segment. This is required for SQL segments.

factTableId
string

ID of the fact table this segment belongs to. This is required for FACT segments.

filters
Array of strings

Optional array of fact table filter ids that can further define the Fact Table based Segment.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "owner": "string",
  • "description": "string",
  • "datasourceId": "string",
  • "identifierType": "string",
  • "projects": [
    ],
  • "managedBy": "",
  • "type": "SQL",
  • "query": "string",
  • "factTableId": "string",
  • "filters": [
    ]
}

Response samples

Content type
application/json
{
  • "segment": {
    }
}

Get a single segment

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/segments/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "segment": {
    }
}

Update a single segment

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
name
string

Name of the segment

owner
string

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.

description
string <= 10000 characters

Description of the segment

datasourceId
string

ID of the datasource this segment belongs to

identifierType
string

Type of identifier (user, anonymous, etc.)

projects
Array of strings

List of project IDs for projects that can access this segment

managedBy
string
Enum: "" "api"

Where this Segment must be managed from. If not set (empty string), it can be managed from anywhere.

type
string
Enum: "SQL" "FACT"

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.

query
string

SQL query that defines the Segment. This is required for SQL segments.

factTableId
string

ID of the fact table this segment belongs to. This is required for FACT segments.

filters
Array of strings

Optional array of fact table filter ids that can further define the Fact Table based Segment.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "owner": "string",
  • "description": "string",
  • "datasourceId": "string",
  • "identifierType": "string",
  • "projects": [
    ],
  • "managedBy": "",
  • "type": "SQL",
  • "query": "string",
  • "factTableId": "string",
  • "filters": [
    ]
}

Response samples

Content type
application/json
{
  • "segment": {
    }
}

Deletes a single segment

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/segments/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "seg_123abc"
}

Experiment Reports

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.

Get all reports

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

experimentId
string

Filter reports by experiment id

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/reports' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "reports": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a new report

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
experimentId
required
string

The experiment to create a report for

title
string

Report title (defaults to experiment name)

description
string

Report description

statsEngine
string
Enum: "bayesian" "frequentist"

Stats engine override

goalMetrics
Array of strings

Goal metric IDs (defaults to experiment's goal metrics)

secondaryMetrics
Array of strings

Secondary metric IDs (defaults to experiment's secondary metrics)

guardrailMetrics
Array of strings

Guardrail metric IDs (defaults to experiment's guardrail metrics)

activationMetric
string

Activation metric ID

dimension
string

Dimension to cut results by

dateStarted
string <date-time>

Analysis start date (ISO 8601)

dateEnded
string <date-time>

Analysis end date (ISO 8601)

regressionAdjustmentEnabled
boolean

Enable CUPED regression adjustment

sequentialTestingEnabled
boolean

Enable sequential testing

sequentialTestingTuningParameter
number

Tuning parameter for sequential testing (frequentist only)

differenceType
string
Enum: "relative" "absolute" "scaled"

How lifts are expressed in results. Defaults to experiment setting.

attributionModel
string
Enum: "firstExposure" "experimentDuration" "lookbackOverride"

Metric conversion window attribution model. Defaults to experiment setting.

object or object

Lookback window when attributionModel is lookbackOverride

Array of objects

Per-metric window, risk, and regression-adjustment overrides

Array of objects

Custom metric slice definitions

segment
string

Segment ID to filter users by. Defaults to experiment setting.

queryFilter
string

Raw SQL WHERE clause added to the exposure query. Defaults to experiment setting.

skipPartialData
boolean

When true, exclude users who have not completed the full conversion window.

shareLevel
string
Enum: "public" "organization" "private"

Visibility of the created report. Defaults to private. Set to public to receive a shareable shareUrl in the response.

Responses

Request samples

Content type
application/json
{
  • "experimentId": "string",
  • "title": "string",
  • "description": "string",
  • "statsEngine": "bayesian",
  • "goalMetrics": [
    ],
  • "secondaryMetrics": [
    ],
  • "guardrailMetrics": [
    ],
  • "activationMetric": "string",
  • "dimension": "string",
  • "dateStarted": "2019-08-24T14:15:22Z",
  • "dateEnded": "2019-08-24T14:15:22Z",
  • "regressionAdjustmentEnabled": true,
  • "sequentialTestingEnabled": true,
  • "sequentialTestingTuningParameter": 0,
  • "differenceType": "relative",
  • "attributionModel": "firstExposure",
  • "lookbackOverride": {
    },
  • "metricOverrides": [
    ],
  • "customMetricSlices": [
    ],
  • "segment": "string",
  • "queryFilter": "string",
  • "skipPartialData": true,
  • "shareLevel": "public"
}

Response samples

Content type
application/json
{
  • "report": {
    }
}

Get a single report

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/reports/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "report": {
    }
}

Refresh a report by re-running its analysis

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X POST 'https://api.growthbook.io/api/v1/reports/{id}/refresh' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "report": {
    }
}

Update report metadata (title, description, visibility)

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
title
string

Report title

description
string

Report description

status
string
Enum: "published" "private"

UI lifecycle marker for the report

shareLevel
string
Enum: "public" "organization" "private"

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).

editLevel
string
Enum: "organization" "private"

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.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "status": "published",
  • "shareLevel": "public",
  • "editLevel": "organization"
}

Response samples

Content type
application/json
{
  • "report": {
    }
}

Update report analysis settings

Updates the analysis settings for an existing report. Changes are staged and do not take effect until you call POST /reports/:id/refresh.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
statsEngine
string
Enum: "bayesian" "frequentist"

Stats engine override

goalMetrics
Array of strings

Goal metric IDs

secondaryMetrics
Array of strings

Secondary metric IDs

guardrailMetrics
Array of strings

Guardrail metric IDs

activationMetric
string

Activation metric ID

Array of objects

Per-metric window, risk, and regression-adjustment overrides

Array of objects

Custom metric slice definitions

dimension
string

Dimension to cut results by

differenceType
string
Enum: "relative" "absolute" "scaled"

How lifts are expressed in results

dateStarted
string <date-time>

Analysis start date (ISO 8601)

string or null

Analysis end date (ISO 8601). Pass null to clear the end date and analyze through today.

regressionAdjustmentEnabled
boolean

Enable CUPED regression adjustment

sequentialTestingEnabled
boolean

Enable sequential testing

sequentialTestingTuningParameter
number

Tuning parameter for sequential testing (frequentist only)

attributionModel
string
Enum: "firstExposure" "experimentDuration" "lookbackOverride"

Metric conversion window attribution model

object or object

Lookback window when attributionModel is lookbackOverride

segment
string

Segment ID to filter users by

queryFilter
string

Raw SQL WHERE clause added to the exposure query

skipPartialData
boolean

When true, exclude users who have not completed the full conversion window

Array of objects

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.

coverage
number [ 0 .. 1 ]

Traffic coverage (0–1) for the latest phase. Used when computing scaled impact.

Responses

Request samples

Content type
application/json
{
  • "statsEngine": "bayesian",
  • "goalMetrics": [
    ],
  • "secondaryMetrics": [
    ],
  • "guardrailMetrics": [
    ],
  • "activationMetric": "string",
  • "metricOverrides": [
    ],
  • "customMetricSlices": [
    ],
  • "dimension": "string",
  • "differenceType": "relative",
  • "dateStarted": "2019-08-24T14:15:22Z",
  • "dateEnded": "2019-08-24T14:15:22Z",
  • "regressionAdjustmentEnabled": true,
  • "sequentialTestingEnabled": true,
  • "sequentialTestingTuningParameter": 0,
  • "attributionModel": "firstExposure",
  • "lookbackOverride": {
    },
  • "segment": "string",
  • "queryFilter": "string",
  • "skipPartialData": true,
  • "variations": [
    ],
  • "coverage": 1
}

Response samples

Content type
application/json
{
  • "report": {
    }
}

SDK Connections

Client keys and settings for connecting SDKs to a GrowthBook instance

Get all sdk connections

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

projectId
string

Filter by project id

withProxy
string
multiOrg
string

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/sdk-connections' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "connections": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a single sdk connection

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
name
required
string
language
required
string
sdkVersion
string
environment
required
string
projects
Array of strings
encryptPayload
boolean
includeVisualExperiments
boolean
includeDraftExperiments
boolean
includeDraftExperimentRefs
boolean

When true, experiment-ref rules linked to draft experiments are included in feature definitions. Off by default.

includeExperimentNames
boolean
includeRedirectExperiments
boolean
includeRuleIds
boolean
includeProjectIdInMetadata
boolean
includeCustomFieldsInMetadata
boolean
allowedCustomFieldsInMetadata
Array of strings
includeTagsInMetadata
boolean
proxyEnabled
boolean
proxyHost
string
hashSecureAttributes
boolean
remoteEvalEnabled
boolean
savedGroupReferencesEnabled
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "language": "string",
  • "sdkVersion": "string",
  • "environment": "string",
  • "projects": [
    ],
  • "encryptPayload": true,
  • "includeVisualExperiments": true,
  • "includeDraftExperiments": true,
  • "includeDraftExperimentRefs": true,
  • "includeExperimentNames": true,
  • "includeRedirectExperiments": true,
  • "includeRuleIds": true,
  • "includeProjectIdInMetadata": true,
  • "includeCustomFieldsInMetadata": true,
  • "allowedCustomFieldsInMetadata": [
    ],
  • "includeTagsInMetadata": true,
  • "proxyEnabled": true,
  • "proxyHost": "string",
  • "hashSecureAttributes": true,
  • "remoteEvalEnabled": true,
  • "savedGroupReferencesEnabled": true
}

Response samples

Content type
application/json
{
  • "sdkConnection": {
    }
}

Get a single sdk connection

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/sdk-connections/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "sdkConnection": {
    }
}

Update a single sdk connection

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
name
string
language
string
sdkVersion
string
environment
string
projects
Array of strings
encryptPayload
boolean
includeVisualExperiments
boolean
includeDraftExperiments
boolean
includeDraftExperimentRefs
boolean

When true, experiment-ref rules linked to draft experiments are included in feature definitions. Off by default.

includeExperimentNames
boolean
includeRedirectExperiments
boolean
includeRuleIds
boolean
includeProjectIdInMetadata
boolean
includeCustomFieldsInMetadata
boolean
allowedCustomFieldsInMetadata
Array of strings
includeTagsInMetadata
boolean
proxyEnabled
boolean
proxyHost
string
hashSecureAttributes
boolean
remoteEvalEnabled
boolean
savedGroupReferencesEnabled
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "language": "string",
  • "sdkVersion": "string",
  • "environment": "string",
  • "projects": [
    ],
  • "encryptPayload": true,
  • "includeVisualExperiments": true,
  • "includeDraftExperiments": true,
  • "includeDraftExperimentRefs": true,
  • "includeExperimentNames": true,
  • "includeRedirectExperiments": true,
  • "includeRuleIds": true,
  • "includeProjectIdInMetadata": true,
  • "includeCustomFieldsInMetadata": true,
  • "allowedCustomFieldsInMetadata": [
    ],
  • "includeTagsInMetadata": true,
  • "proxyEnabled": true,
  • "proxyHost": "string",
  • "hashSecureAttributes": true,
  • "remoteEvalEnabled": true,
  • "savedGroupReferencesEnabled": true
}

Response samples

Content type
application/json
{
  • "sdkConnection": {
    }
}

Deletes a single SDK connection

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/sdk-connections/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "string"
}

Find a single sdk connection by its key

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string

The key of the requested sdkConnection

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/sdk-connections/lookup/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "sdkConnection": {
    }
}

Visual Changesets

Groups of visual changes made by the visual editor to a single page

Get all visual changesets

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The experiment id the visual changesets belong to

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/experiments/abc123/visual-changesets' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "visualChangesets": [
    ]
}

Create a visual changeset for an experiment

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
editorUrl
required
string

URL of the page opened in the visual editor when creating this changeset

required
Array of objects

URL patterns that determine which pages this visual changeset applies to

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "editorUrl": "string",
  • "urlPatterns": [
    ],
  • "property1": null,
  • "property2": null
}

Response samples

Content type
application/json
{
  • "visualChangeset": {
    }
}

Get a single visual changeset

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

query Parameters
includeExperiment
integer

Include the associated experiment in payload

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/visual-changesets/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "visualChangeset": {
    },
  • "experiment": {
    }
}

Update a visual changeset

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
editorUrl
string

URL of the page opened in the visual editor when creating this changeset

Array of objects

URL patterns that determine which pages this visual changeset applies to

Array of objects
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "editorUrl": "string",
  • "urlPatterns": [
    ],
  • "visualChanges": [
    ],
  • "property1": null,
  • "property2": null
}

Response samples

Content type
application/json
{
  • "nModified": 0,
  • "visualChangeset": {
    }
}

Create a visual change for a visual changeset

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
id
string
description
string
css
string
js
string
variation
required
string
Array of objects
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "description": "string",
  • "css": "string",
  • "js": "string",
  • "variation": "string",
  • "domMutations": [
    ],
  • "property1": null,
  • "property2": null
}

Response samples

Content type
application/json
{
  • "nModified": 0,
  • "visualChangeId": "string"
}

Update a visual change for a visual changeset

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

visualChangeId
required
string

Specify a specific visual change

Request Body schema: application/json
required
description
string
css
string
js
string
variation
string
Array of objects
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "css": "string",
  • "js": "string",
  • "variation": "string",
  • "domMutations": [
    ],
  • "property1": null,
  • "property2": null
}

Response samples

Content type
application/json
{
  • "nModified": 0
}

Saved Groups

Defined sets of attribute values which can be used with feature rules for targeting features at particular users.

Get all saved group

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/saved-groups' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "savedGroups": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a single saved group

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
name
required
string

The display name of the Saved Group

type
string
Enum: "condition" "list"

The type of Saved Group (inferred from other arguments if missing)

condition
string

When type = 'condition', this is the JSON-encoded condition for the group

attributeKey
string

When type = 'list', this is the attribute key the group is based on

values
Array of strings

When type = 'list', this is the list of values for the attribute key

owner
string

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 user associated with the request's Personal Access Token (PAT), if one is being used.

projects
Array of strings
bypassApproval
boolean

Set to true to skip the approval flow when the org requires approvals on saved groups. Requires the bypassApprovalChecks permission on every project the saved group belongs to. When the org does not require approvals, this flag has no effect.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "condition",
  • "condition": "string",
  • "attributeKey": "string",
  • "values": [
    ],
  • "owner": "string",
  • "projects": [
    ],
  • "bypassApproval": true
}

Response samples

Content type
application/json
{
  • "savedGroup": {
    }
}

Get a single saved group

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/saved-groups/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "savedGroup": {
    }
}

Partially update a single saved group

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
name
string

The display name of the Saved Group

condition
string

When type = 'condition', this is the JSON-encoded condition for the group

values
Array of strings

When type = 'list', this is the list of values for the attribute key

owner
string

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.

projects
Array of strings
bypassApproval
boolean

Set to true to skip the approval flow when the org requires approvals on saved groups. Requires the bypassApprovalChecks permission on the saved group's existing projects. When the org does not require approvals, this flag has no effect.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "condition": "string",
  • "values": [
    ],
  • "owner": "string",
  • "projects": [
    ],
  • "bypassApproval": true
}

Response samples

Content type
application/json
{
  • "savedGroup": {
    }
}

Deletes a single saved group

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/saved-groups/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "string"
}

Archive a single saved group

Archives a saved group. When live features, experiments, or other saved groups still reference it, the request returns a 422 listing the blocking gates — re-submit with "ignoreWarnings": true in the request body to acknowledge the affected references and proceed. If the organization requires approval for saved-group changes, the request returns an approval-required gate instead: route the change through a draft revision (POST /saved-groups/{id}/revisions), or use a role or token with the bypass-approvals permission. Any gate the caller's authority bypasses is reported in bypassedGates on success.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "savedGroup": {
    },
  • "bypassedGates": [
    ]
}

Unarchive a single saved group

Unarchives a saved group. Unarchiving never drops a dependent, but if the organization requires approval for saved-group changes the request returns an approval-required gate — route the change through a draft revision (POST /saved-groups/{id}/revisions), or use a role or token with the bypass-approvals permission. Any gate the caller's authority bypasses is reported in bypassedGates.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X POST 'https://api.growthbook.io/api/v1/saved-groups/abc123/unarchive' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "savedGroup": {
    },
  • "bypassedGates": [
    ]
}

Get features, experiments, and saved groups that reference this saved group

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/saved-groups/abc123/references' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "features": [
    ],
  • "experiments": [
    ],
  • "savedGroups": [
    ]
}

Saved Group Revisions

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.

List saved-group revisions across the organization

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.

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Default: false

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.

savedGroupId
string

Restrict results to revisions for a single saved group. When omitted, returns revisions across every saved group the caller can read.

status
string

Filter by revision status. Accepts a comma-separated list, or the literal open for non-merged/non-discarded revisions.

author
string
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean

If true, return only revisions authored by the calling user. Requires a user-scoped API key. Mutually exclusive with author.

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/saved-groups-revisions' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revisions": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

List revisions for a saved group

Returns a paginated list of revisions for this saved group, sorted newest-first. Optionally filtered by status, author, or the calling user's involvement.

Authorizations:
bearerAuthbasicAuth
path Parameters
savedGroupId
required
string
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Default: false

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.

status
string

Filter by revision status. Accepts a comma-separated list, or the literal open for non-merged/non-discarded revisions.

author
string
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean

If true, return only revisions authored by the calling user. Requires a user-scoped API key. Mutually exclusive with author.

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/saved-groups-revisions/grp_abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revisions": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
savedGroupId
required
string
Request Body schema: application/json
required
title
string
comment
string

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Get the most recent active draft revision

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 (requires a user-scoped API key).

Authorizations:
bearerAuthbasicAuth
path Parameters
savedGroupId
required
string
query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean

If true, return only the most recent active draft authored by the calling user. Requires a user-scoped API key.

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/saved-groups-revisions/grp_abc123/latest' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Get a single saved group revision

Returns the revision at the specified version for this saved group. Use GET /saved-groups-revisions/{savedGroupId}/latest for the most recent active draft.

Authorizations:
bearerAuthbasicAuth
path Parameters
savedGroupId
required
string
version
required
integer

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/saved-groups-revisions/grp_abc123/3' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Update saved group metadata in a draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
savedGroupId
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
revisionTitle
string
revisionComment
string
name
string
owner
string

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.

description
string
projects
Array of strings

Responses

Request samples

Content type
application/json
{
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "name": "string",
  • "owner": "string",
  • "description": "string",
  • "projects": [
    ]
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Update the condition of a condition saved group draft revision

Stages a new JSON-encoded condition for the draft. Only valid for condition saved groups. Pass version: "new" to auto-create a draft.

Authorizations:
bearerAuthbasicAuth
path Parameters
savedGroupId
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
revisionTitle
string
revisionComment
string
condition
required
string

The JSON-encoded condition for the saved group

Responses

Request samples

Content type
application/json
{
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "condition": "string"
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Replace the values list in a list saved group draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
savedGroupId
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
revisionTitle
string
revisionComment
string
values
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "values": [
    ]
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Stage an archive/unarchive in a draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
savedGroupId
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
revisionTitle
string
revisionComment
string
archived
required
boolean

Responses

Request samples

Content type
application/json
{
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "archived": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Append items to a list saved group draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
savedGroupId
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
revisionTitle
string
revisionComment
string
items
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Remove items from a list saved group draft revision

Removes the provided items from the draft's values array. Only valid for list saved groups. Pass version: "new" to auto-create a draft.

Authorizations:
bearerAuthbasicAuth
path Parameters
savedGroupId
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
revisionTitle
string
revisionComment
string
items
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Request review for a draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
savedGroupId
required
string
version
required
integer
Request Body schema: application/json
required
autoPublishOnApproval
boolean

Responses

Request samples

Content type
application/json
{
  • "autoPublishOnApproval": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Submit a review on a draft revision

Submits an approve, request-changes, or comment review on the revision. 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.

Authorizations:
bearerAuthbasicAuth
path Parameters
savedGroupId
required
string
version
required
integer
Request Body schema: application/json
required
decision
required
string
Enum: "approve" "request-changes" "comment"
comment
string
skipAutoPublish
boolean

Responses

Request samples

Content type
application/json
{
  • "decision": "approve",
  • "comment": "string",
  • "skipAutoPublish": true
}

Response samples

Content type
application/json
{
  • "revision": {
    },
  • "autoPublished": true
}

Get merge status for a draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
savedGroupId
required
string
version
required
integer

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/saved-groups-revisions/{savedGroupId}/{version}/merge-status' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "success": true,
  • "hasConflicts": true,
  • "conflicts": [
    ],
  • "canAutoMerge": true
}

Rebase a draft revision onto the current live saved group

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
savedGroupId
required
string
version
required
integer
Request Body schema: application/json
required
object
object

Custom values to use for union strategy fields. Keyed by field name.

Responses

Request samples

Content type
application/json
{
  • "conflictResolutions": {
    },
  • "customValues": {
    }
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Publish a draft revision

Publishes a draft revision, making it the live state of the saved group. Blocked if the org requires approvals and the revision is not approved (callers with the bypass-approval permission may still publish). Under requireRebaseBeforePublish, a draft whose base has moved since it was created is blocked until rebased — a caller with the bypass-approval permission can force-merge instead by passing ignoreWarnings: true (the permission alone does not silently skip the rebase). When blocked, the 422 lists every applicable gate and how to clear each (see the response docs).

Authorizations:
bearerAuthbasicAuth
path Parameters
savedGroupId
required
string
version
required
integer
Request Body schema: application/json
required
bypassApproval
boolean

Has no effect and is accepted only for backwards compatibility. Callers with the bypassApprovalChecks permission (or under the org-level REST bypass setting) bypass approval requirements automatically; all other callers must have the revision approved before publishing.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "bypassApproval": true,
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    },
  • "bypassedGates": [
    ]
}

Discard a draft revision

Permanently discards a draft revision. Only open revisions (not merged or already-discarded) can be discarded.

Authorizations:
bearerAuthbasicAuth
path Parameters
savedGroupId
required
string
version
required
integer
Request Body schema: application/json
required
reason
string

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Revert the saved group to a prior revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
savedGroupId
required
string
version
required
integer
Request Body schema: application/json
required
strategy
string
Enum: "draft" "publish"
title
string
comment
string

Responses

Request samples

Content type
application/json
{
  • "strategy": "draft",
  • "title": "string",
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Constants

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.)

Get all constants

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/constants' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "constants": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a single constant

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
key
required
string^[a-z0-9][a-z0-9\-_]*$

Stable reference handle (lowercase slug, unique per org), referenced as @const:key

name
required
string

The display name of the constant

type
required
string
Enum: "string" "json"

string (interpolated as {{ @const:key }}) or json (substituted as a whole value)

value
string
object
description
string <= 10000 characters
project
string
owner
string

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 user associated with the request's Personal Access Token (PAT), if one is being used.

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "name": "string",
  • "type": "string",
  • "value": "string",
  • "environmentValues": {
    },
  • "description": "string",
  • "project": "string",
  • "owner": "string"
}

Response samples

Content type
application/json
{
  • "constant": {
    }
}

Get features and constants that reference this constant

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string

The key of the constant

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/constants/config-snippet/references' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "features": [
    ],
  • "constants": [
    ]
}

Get a single constant

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string

The key of the constant

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/constants/config-snippet' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "constant": {
    }
}

Partially update a single constant

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string

The key of the constant

Request Body schema: application/json
required
name
string
value
string
object

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).

description
string <= 10000 characters
project
string
owner
string

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.

bypassApproval
boolean

Set to true to skip the approval flow when the org requires approvals for this constant's project. Requires the bypassApprovalChecks permission (or the org-level REST bypass setting). When approvals aren't required, this flag has no effect.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "value": "string",
  • "environmentValues": {
    },
  • "description": "string",
  • "project": "string",
  • "owner": "string",
  • "bypassApproval": true,
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "constant": {
    }
}

Delete a single constant

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string

The key of the constant

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/constants/config-snippet' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "string"
}

Archive a single constant

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string

The key of the constant

Request Body schema: application/json
required
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "constant": {
    },
  • "bypassedGates": [
    ]
}

Unarchive a single constant

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string

The key of the constant

Request Body schema: application/json
required
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "constant": {
    },
  • "bypassedGates": [
    ]
}

Constant Revisions

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.

List constant revisions across the organization

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.

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Default: false

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.

key
string

Restrict results to revisions for a single constant (by its key). When omitted, returns revisions across every constant the caller can read.

status
string

Filter by revision status. Accepts a comma-separated list, or the literal open for non-merged/non-discarded revisions.

author
string
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean

If true, return only revisions authored by the calling user. Requires a user-scoped API key. Mutually exclusive with author.

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/constants-revisions' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revisions": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

List revisions for a constant

Returns a paginated list of revisions for this constant, sorted newest-first. Optionally filtered by status, author, or the calling user's involvement.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Default: false

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.

status
string

Filter by revision status. Accepts a comma-separated list, or the literal open for non-merged/non-discarded revisions.

author
string
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean

If true, return only revisions authored by the calling user. Requires a user-scoped API key. Mutually exclusive with author.

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/constants-revisions/config-snippet' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revisions": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
Request Body schema: application/json
required
title
string
comment
string

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Get the most recent active draft revision

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 (requires a user-scoped API key).

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean

If true, return only the most recent active draft authored by the calling user. Requires a user-scoped API key.

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/constants-revisions/config-snippet/latest' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Get a single constant revision

Returns the revision at the specified version for this constant. Use GET /constants-revisions/{key}/latest for the most recent active draft.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
version
required
integer

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/constants-revisions/config-snippet/3' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Update constant metadata in a draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
revisionTitle
string
revisionComment
string
name
string
owner
string

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.

description
string
project
string

Responses

Request samples

Content type
application/json
{
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "name": "string",
  • "owner": "string",
  • "description": "string",
  • "project": "string"
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Update the value of a constant draft revision

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).

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
revisionTitle
string
revisionComment
string
value
string

The default value (raw string for string constants, JSON-encoded for json constants)

object

Per-environment value overrides (environment id → value)

Responses

Request samples

Content type
application/json
{
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "value": "string",
  • "environmentValues": {
    }
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Stage an archive/unarchive in a draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
revisionTitle
string
revisionComment
string
archived
required
boolean

Responses

Request samples

Content type
application/json
{
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "archived": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Request review for a draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
version
required
integer
Request Body schema: application/json
required
autoPublishOnApproval
boolean
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

Responses

Request samples

Content type
application/json
{
  • "autoPublishOnApproval": true,
  • "ignoreWarnings": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Submit a review on a draft revision

Submits an approve, request-changes, or comment review on the revision. 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.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
version
required
integer
Request Body schema: application/json
required
decision
required
string
Enum: "approve" "request-changes" "comment"
comment
string
skipAutoPublish
boolean

Responses

Request samples

Content type
application/json
{
  • "decision": "approve",
  • "comment": "string",
  • "skipAutoPublish": true
}

Response samples

Content type
application/json
{
  • "revision": {
    },
  • "autoPublished": true
}

Get merge status for a draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
version
required
integer

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/constants-revisions/{key}/{version}/merge-status' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "success": true,
  • "hasConflicts": true,
  • "conflicts": [
    ],
  • "canAutoMerge": true
}

Rebase a draft revision onto the current live constant

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).

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
version
required
integer
Request Body schema: application/json
required
object
property name*
additional property
string
Enum: "overwrite" "discard"

Responses

Request samples

Content type
application/json
{
  • "conflictResolutions": {
    }
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Publish a draft revision

Publishes a draft revision, making it the live state of the constant. Blocked if the org requires approvals and the revision is not approved (callers with the bypass-approval permission may still publish). Under requireRebaseBeforePublish, a draft whose base has moved since it was created is blocked until rebased — a caller with the bypass-approval permission can force-merge instead by passing ignoreWarnings: true (the permission alone does not silently skip the rebase). When blocked, the 422 lists every applicable gate and how to clear each (see the response docs).

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
version
required
integer
Request Body schema: application/json
required
bypassApproval
boolean

Has no effect and is accepted only for backwards compatibility. Callers with the bypassApprovalChecks permission (or under the org-level REST bypass setting) bypass approval requirements automatically; all other callers must have the revision approved before publishing.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "bypassApproval": true,
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "revision": {
    },
  • "bypassedGates": [
    ]
}

Discard a draft revision

Permanently discards a draft revision. Only open revisions (not merged or already-discarded) can be discarded.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
version
required
integer
Request Body schema: application/json
required
reason
string

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Revert the constant to a prior revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
version
required
integer
Request Body schema: application/json
required
strategy
string
Enum: "draft" "publish"
title
string
comment
string
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "strategy": "draft",
  • "title": "string",
  • "comment": "string",
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Configs

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.

Get all configs

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/configs' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "configs": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a single config

Authorizations:
bearerAuthbasicAuth
query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass skipSchemaValidation in the request body instead.

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass ignoreWarnings in the request body instead.

Request Body schema: application/json
required
key
required
string^[a-z0-9][a-z0-9\-_]*$

Stable reference handle (lowercase slug, unique per org), referenced as @config:key

name
required
string

The display name of the config

parent
string

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).

extends
Array of strings

Additional composition bases (config keys) 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.

object

This config's base value as a JSON object. Per-environment/project variants are expressed via scopedOverrides.

Array of objects

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).

description
string <= 10000 characters
project
string
owner
string

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 user associated with the request's Personal Access Token (PAT), if one is being used.

ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) (ConfigSchemaSource)
source
string

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=<id>&format=<lang> can reproduce those names.

extensible
boolean
experimentGuard
boolean

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.

Array of objects

Cross-field validation rules. Each rule's expression is a mongo condition (mongrule). Stored on the config schema and enforced at publish.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "name": "string",
  • "parent": "string",
  • "extends": [
    ],
  • "value": {
    },
  • "scopedOverrides": [
    ],
  • "description": "string",
  • "project": "string",
  • "owner": "string",
  • "schema": {
    },
  • "source": "string",
  • "extensible": true,
  • "experimentGuard": true,
  • "invariants": [
    ],
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "config": {
    },
  • "warnings": [
    ]
}

Get features and configs that reference this config

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string

The key of the config

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/configs/checkout-flow/references' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "features": [
    ],
  • "constants": [
    ]
}

Get the feature rules and default values implementing each key

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string

The key of the config

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/configs/checkout-flow/key-usage' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "familyKeys": [
    ],
  • "implementations": [
    ]
}

Get the full lineage (family tree) for a config

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string

The key of the config

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/configs/checkout-flow/lineage' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "root": "string",
  • "target": "string",
  • "ancestors": [
    ],
  • "descendants": [
    ],
  • "nodes": [
    ]
}

Verify a config's schema against a source (drift check)

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string

The key of the config

Request Body schema: application/json
required
required
ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) (ConfigSchemaSource)
Any of
type
required
string
Value: "json-schema"
required
object

A JSON Schema document (an object).

Responses

Request samples

Content type
application/json
{
  • "schema": {
    }
}

Response samples

Content type
application/json
{
  • "inSync": true,
  • "fingerprint": "string",
  • "incomingFingerprint": "string",
  • "drift": {
    },
  • "ancestorOwnedFields": [
    ],
  • "warnings": [
    ]
}

Export a config's schema

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string

The key of the config

query Parameters
format
string
Enum: "json-schema" "typescript" "protobuf" "python" "go" "rust"

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.

"true" (string) or "false" (string) or boolean

When true, includes fields inherited across the lineage (the family's accumulated schema). When false (default), returns only this config's own fields.

source
string

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.

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/configs/checkout-flow/schema' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "schema": {
    },
  • "effective": true,
  • "additionalProperties": true
}

Get a single config

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string

The key of the config

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/configs/checkout-flow' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "config": {
    }
}

Partially update a single config

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string

The key of the config

query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass skipSchemaValidation in the request body instead.

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass ignoreWarnings in the request body instead.

Request Body schema: application/json
required
name
string
parent
string

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.

extends
Array of strings

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.

object

This config's base value as a JSON object. Per-environment/project variants are expressed via scopedOverrides.

Array of objects

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.

description
string <= 10000 characters
project
string
owner
string

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.

ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) (ConfigSchemaSource)
source
string

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.

extensible
boolean
experimentGuard
boolean

Enable or disable the experiment guard on this config. Turning it OFF requires the bypassApprovalChecks permission.

Array of objects

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.

bypassApproval
boolean

Set to true to skip the approval flow when the org requires approvals for this config's project. Requires the bypassApprovalChecks permission (or the org-level REST bypass setting). When approvals aren't required, this flag has no effect.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "parent": "string",
  • "extends": [
    ],
  • "value": {
    },
  • "scopedOverrides": [
    ],
  • "description": "string",
  • "project": "string",
  • "owner": "string",
  • "schema": {
    },
  • "source": "string",
  • "extensible": true,
  • "experimentGuard": true,
  • "invariants": [
    ],
  • "bypassApproval": true,
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "config": {
    },
  • "warnings": [
    ]
}

Delete a single config

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string

The key of the config

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/configs/checkout-flow' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "string"
}

Archive a single config

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).

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string

The key of the config

query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass ignoreWarnings in the request body instead.

Request Body schema: application/json
required
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "config": {
    },
  • "bypassedGates": [
    ]
}

Unarchive a single config

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string

The key of the config

Request Body schema: application/json
required
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "config": {
    },
  • "bypassedGates": [
    ]
}

Lock a config at its current published revision

Freezes the config at its current published (merged) revision. While locked, no change can be published past that revision — publish, revert-to-publish, direct update, scheduled publish, and archive are all blocked (drafts may still be created and edited). The pinned revision is returned as lockedRevision for reproducible build pinning. Unlocking requires the bypassApprovalChecks permission.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string

The key of the config

Request Body schema: application/json
required
reason
string <= 10000 characters

Optional note explaining why the config was locked.

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "config": {
    }
}

Unlock a config

Clears the lock so changes can be published again. Requires the bypassApprovalChecks permission on the config's project.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string

The key of the config

Responses

Request samples 

curl -X POST 'https://api.growthbook.io/api/v1/configs/checkout-flow/unlock' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "config": {
    }
}

Config Revisions

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.

List config revisions across the organization

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.

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Default: false

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.

key
string

Restrict results to revisions for a single config (by its key). When omitted, returns revisions across every config the caller can read.

status
string

Filter by revision status. Accepts a comma-separated list, or the literal open for non-merged/non-discarded revisions.

author
string
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean

If true, return only revisions authored by the calling user. Requires a user-scoped API key. Mutually exclusive with author.

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/configs-revisions' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revisions": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

List revisions for a config

Returns a paginated list of revisions for this config, sorted newest-first. Optionally filtered by status, author, or the calling user's involvement.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Default: false

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.

status
string

Filter by revision status. Accepts a comma-separated list, or the literal open for non-merged/non-discarded revisions.

author
string
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean

If true, return only revisions authored by the calling user. Requires a user-scoped API key. Mutually exclusive with author.

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/configs-revisions/checkout-flow' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revisions": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
Request Body schema: application/json
required
title
string
comment
string

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Get the most recent active draft revision

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 (requires a user-scoped API key).

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean

If true, return only the most recent active draft authored by the calling user. Requires a user-scoped API key.

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/configs-revisions/checkout-flow/latest' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Get a single config revision

Returns the revision at the specified version for this config. Use GET /configs-revisions/{key}/latest for the most recent active draft.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
version
required
integer

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/configs-revisions/checkout-flow/3' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Update config metadata in a draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
required
integer or "new" (string)
query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass skipSchemaValidation in the request body instead.

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass ignoreWarnings in the request body instead.

Request Body schema: application/json
required
revisionTitle
string
revisionComment
string
name
string
owner
string

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.

description
string
project
string
parent
string

Change the lineage parent (the key to inherit from). Empty string detaches from the parent.

extends
Array of strings

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.

extensible
boolean
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "name": "string",
  • "owner": "string",
  • "description": "string",
  • "project": "string",
  • "parent": "string",
  • "extends": [
    ],
  • "extensible": true,
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "revision": {
    },
  • "warnings": [
    ]
}

Update the value of a config draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
required
integer or "new" (string)
query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass skipSchemaValidation in the request body instead.

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass ignoreWarnings in the request body instead.

Request Body schema: application/json
required
revisionTitle
string
revisionComment
string
object

This config's own value as a JSON object — a targeted patch deep-merged onto the resolved parent value.

inferSchemaIfMissing
boolean

When the config has no schema yet, infer one from the supplied value and stage it on the same draft.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "value": {
    },
  • "inferSchemaIfMissing": true,
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "revision": {
    },
  • "warnings": [
    ]
}

Update or import the schema of a config draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
required
integer or "new" (string)
query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass skipSchemaValidation in the request body instead.

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass ignoreWarnings in the request body instead.

Request Body schema: application/json
required
revisionTitle
string
revisionComment
string
ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) (ConfigSchemaSource)
infer
boolean

Derive the schema from the draft's value instead.

additionalProperties
boolean

Whether the resulting object schema permits extra keys (family extensibility).

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "schema": {
    },
  • "infer": true,
  • "additionalProperties": true,
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "revision": {
    },
  • "warnings": [
    ]
}

Set (or update) a config's per-source render projection on a draft

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
required
integer or "new" (string)
query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass skipSchemaValidation in the request body instead.

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass ignoreWarnings in the request body instead.

Request Body schema: application/json
required
revisionTitle
string
revisionComment
string
source
required
string

Identifier of the consuming codebase/service this projection belongs to.

required
ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) (ConfigSchemaSource)
additionalProperties
boolean

Whether the resulting object schema permits extra keys (family extensibility).

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "source": "string",
  • "schema": {
    },
  • "additionalProperties": true,
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "revision": {
    },
  • "warnings": [
    ]
}

Remove a config's per-source render projection on a draft

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
required
integer or "new" (string)
query Parameters
source
required
string

Identifier of the projection (source) to remove.

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/projection' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Stage an archive/unarchive in a draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
required
integer or "new" (string)
Request Body schema: application/json
required
revisionTitle
string
revisionComment
string
archived
required
boolean
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "revisionTitle": "string",
  • "revisionComment": "string",
  • "archived": true,
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Request review for a draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
version
required
integer
Request Body schema: application/json
required
autoPublishOnApproval
boolean
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "autoPublishOnApproval": true,
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Submit a review on a draft revision

Submits an approve, request-changes, or comment review on the revision. 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.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
version
required
integer
Request Body schema: application/json
required
decision
required
string
Enum: "approve" "request-changes" "comment"
comment
string
skipAutoPublish
boolean

Responses

Request samples

Content type
application/json
{
  • "decision": "approve",
  • "comment": "string",
  • "skipAutoPublish": true
}

Response samples

Content type
application/json
{
  • "revision": {
    },
  • "autoPublished": true
}

Recall a review request

Pulls a revision in review (pending-review, changes-requested, or approved) back to draft, clearing existing reviews and disarming any auto-publish-on-approval.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
version
required
integer
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Reopen a discarded revision

Returns a previously discarded revision to draft status so it can be edited and published again. Only discarded revisions can be reopened.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
version
required
integer
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Schedule (or cancel) a deferred publish

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).

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
version
required
integer
Request Body schema: application/json
required
required
string or null
lockEdits
boolean
lockOthers
boolean
bypassApproval
boolean
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "scheduledPublishAt": "string",
  • "lockEdits": true,
  • "lockOthers": true,
  • "bypassApproval": true,
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Get merge status for a draft revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
version
required
integer

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/configs-revisions/{key}/{version}/merge-status' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "success": true,
  • "hasConflicts": true,
  • "conflicts": [
    ],
  • "canAutoMerge": true
}

Rebase a draft revision onto the current live config

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).

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
version
required
integer
Request Body schema: application/json
required
object
object

Custom values to use for union strategy fields. Keyed by field name.

Responses

Request samples

Content type
application/json
{
  • "conflictResolutions": {
    },
  • "customValues": {
    }
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Publish a draft revision

Publishes a draft revision, making it the live state of the config. Blocked if the org requires approvals and the revision is not approved (callers with the bypass-approval permission may still publish). Under requireRebaseBeforePublish, a draft whose base has moved since it was created is blocked until rebased — a caller with the bypass-approval permission can force-merge instead by passing ignoreWarnings: true (the permission alone does not silently skip the rebase). A locked config is blocked until unlocked. When blocked, the 422 lists every applicable gate and how to clear each (see the response docs). Publishing a schema change cascades the 'base wins' normalization to descendant configs.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
version
required
integer
query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass skipSchemaValidation in the request body instead.

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass ignoreWarnings in the request body instead.

Request Body schema: application/json
required
bypassApproval
boolean

Has no effect and is accepted only for backwards compatibility. Callers with the bypassApprovalChecks permission (or under the org-level REST bypass setting) bypass approval requirements automatically; all other callers must have the revision approved before publishing.

ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "bypassApproval": true,
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "revision": {
    },
  • "bypassedGates": [
    ]
}

Discard a draft revision

Permanently discards a draft revision. Only open revisions (not merged or already-discarded) can be discarded.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
version
required
integer
Request Body schema: application/json
required
reason
string

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Revert the config to a prior revision

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
key
required
string
version
required
integer
query Parameters
"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass skipSchemaValidation in the request body instead.

"true" (string) or "false" (string) or "0" (string) or "1" (string) or boolean
Deprecated

Deprecated — pass ignoreWarnings in the request body instead.

Request Body schema: application/json
required
strategy
string
Enum: "draft" "publish"
title
string
comment
string
ignoreWarnings
boolean

Acknowledge and proceed past ACKNOWLEDGE-class warnings: a value served to a running experiment, a locked dependent, and dependents dropped by an archive. A blocked request lists what this would acknowledge in warnings. Does NOT clear validation-class failures (schema errors, cross-field invariants, downstream schema breaks, or custom-hook rejections) — those require skipSchemaValidation — EXCEPT when the org disables 'block publishing on JSON schema errors' (warn mode), where schema, invariant, and schema-break failures become soft and this flag clears them (custom-hook rejections still need skipSchemaValidation). On publish endpoints this also force-merges a draft whose base is stale, when you hold the bypass-approval permission.

skipSchemaValidation
boolean

Force past schema-validation failures: JSON-schema validation of the value(s) written, cross-field invariants, and downstream schema breaks (a change that makes a dependent config or config-backed feature value violate its schema). Does NOT clear a custom validation-hook rejection — use skipHooks for that. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise. Validation is enforced by default.

skipHooks
boolean

Force past a custom validation hook that rejected the change (a hook that threw). Separate from skipSchemaValidation — a hook failure is not a schema error. Only honored for callers with org-wide bypass authority (the bypassApprovalChecks permission on all projects); ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "strategy": "draft",
  • "title": "string",
  • "comment": "string",
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true
}

Response samples

Content type
application/json
{
  • "revision": {
    }
}

Releases

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.

Atomically publish revisions across multiple entities

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.

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
required
Array of FeatureRevisionRef (object) or SavedGroupRevisionRef (object) or ConfigRevisionRef (object) or ConstantRevisionRef (object) or RevisionIdRef (object) [ 1 .. 50 ] items

The revisions to publish, at most one per entity.

dryRun
boolean

Report every gate and outcome without writing anything.

ignoreWarnings
boolean

Acknowledge warning-class gates: experiment guards, schema-break and archive warnings, stale-base force-merge (needs the bypass-approval permission).

skipSchemaValidation
boolean

Force past schema and invariant failures. Only honored with the bypassApprovalChecks permission; validation still runs and is reported.

skipHooks
boolean

Force past custom validation-hook rejections. Only honored with the bypassApprovalChecks permission.

comment
string

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.

Responses

Request samples

Content type
application/json
{
  • "revisions": [
    ],
  • "dryRun": true,
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true,
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "dryRun": true,
  • "bulkPublishId": "string",
  • "results": [
    ],
  • "gates": [
    ],
  • "bypassedGates": [
    ],
  • "warnings": [
    ]
}

Custom Hooks

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.

Get all custom hooks

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/custom-hooks' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "customHooks": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a single custom hook

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
name
required
string

The display name of the custom hook

hook
required
string
Enum: "validateFeature" "validateFeatureRevision" "validateConfig" "validateConfigRevision" "validateExperiment"
code
required
string
enabled
boolean
Default: true
projects
Array of strings

Project ids the hook applies to (empty/omitted = all)

entityType
string
Enum: "feature" "config" "experiment"
entityId
string
incrementalChangesOnly
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "hook": "validateFeature",
  • "code": "string",
  • "enabled": true,
  • "projects": [
    ],
  • "entityType": "feature",
  • "entityId": "string",
  • "incrementalChangesOnly": true
}

Response samples

Content type
application/json
{
  • "customHook": {
    }
}

Dry-run hook code in the sandbox

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
functionBody
required
string

JavaScript function body to execute in the sandbox

object

Arguments exposed to the function as named globals (e.g. feature, config, revision)

entityType
string
Enum: "feature" "config" "experiment"
entityId
string

Responses

Request samples

Content type
application/json
{
  • "functionBody": "string",
  • "functionArgs": {
    },
  • "entityType": "feature",
  • "entityId": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "returnVal": "string",
  • "error": "string",
  • "warnings": [
    ],
  • "log": "string"
}

Get a single custom hook

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the custom hook

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/custom-hooks/hook_123abc' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "customHook": {
    }
}

Partially update a single custom hook

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the custom hook

Request Body schema: application/json
required
name
string
hook
string
Enum: "validateFeature" "validateFeatureRevision" "validateConfig" "validateConfigRevision" "validateExperiment"
code
string
enabled
boolean
projects
Array of strings
string or null

Retarget the hook's scope (set with entityId). Pass null (with entityId: null) to make the hook global/project-scoped; omit to leave unchanged.

string or null

The scoped resource: a feature id, or a config key. Pass null (with entityType: null) to clear the scope; omit to leave unchanged.

incrementalChangesOnly
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "hook": "validateFeature",
  • "code": "string",
  • "enabled": true,
  • "projects": [
    ],
  • "entityType": "feature",
  • "entityId": "string",
  • "incrementalChangesOnly": true
}

Response samples

Content type
application/json
{
  • "customHook": {
    }
}

Delete a single custom hook

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the custom hook

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/custom-hooks/hook_123abc' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "string"
}

List a custom hook's version history

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the custom hook

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/custom-hooks/hook_123abc/history' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "versions": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Revert a custom hook to a previous version

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the custom hook

Request Body schema: application/json
required
auditId
required
string

The version to restore (from the history endpoint)

Responses

Request samples

Content type
application/json
{
  • "auditId": "string"
}

Response samples

Content type
application/json
{
  • "customHook": {
    }
}

Organizations

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.

Get all organizations (only for super admins on multi-org Enterprise Plan only)

Authorizations:
bearerAuthbasicAuth
query Parameters
search
string

Search string to search organization names, owner emails, and external ids by

limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/organizations' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "organizations": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Create a single organization (only for super admins on multi-org Enterprise Plan only)

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
name
required
string

The name of the organization

externalId
string

An optional identifier that you use within your company for the organization

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "externalId": "string"
}

Response samples

Content type
application/json
{
  • "organization": {
    }
}

Edit a single organization (only for super admins on multi-org Enterprise Plan only)

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
name
string

The name of the organization

externalId
string

An optional identifier that you use within your company for the organization

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "externalId": "string"
}

Response samples

Content type
application/json
{
  • "organization": {
    }
}

Members

Members are users who have been invited to an organization.

Get all organization members

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

userName
string

Name of the user.

userEmail
string

Email address of the user.

globalRole
string

Name of the global role

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/members' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "members": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Update a member's global role (including any enviroment restrictions, if applicable). Can also update a member's project roles if your plan supports it.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
required
object
role
string
environments
Array of strings
Array of objects

Responses

Request samples

Content type
application/json
{
  • "member": {
    }
}

Response samples

Content type
application/json
{
  • "updatedMember": {
    }
}

Removes a single user from an organization

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/members/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "string"
}

Code References

Intended for use with our code reference CI utility, gb-find-code-refs.

Submit list of code references

Authorizations:
bearerAuthbasicAuth
query Parameters
deleteMissing
string
Default: "false"
Enum: "true" "false"

Whether to delete code references that are no longer present in the submitted data

Request Body schema: application/json
required
branch
required
string
repoName
required
string
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "branch": "string",
  • "repoName": "string",
  • "refs": [
    ]
}

Response samples

Content type
application/json
{
  • "featuresUpdated": [
    ]
}

Get list of all code references for the current organization

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

The number of items to return

offset
integer >= 0
Default: 0

How many items to skip (use in conjunction with limit for pagination)

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/code-refs' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "codeRefs": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Get list of code references for a single feature id

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/code-refs/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "codeRefs": [
    ]
}

Archetypes

Archetypes allow you to simulate the result of targeting rules on pre-set user attributes

Get the organization's archetypes

Authorizations:
bearerAuthbasicAuth

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/archetypes' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "archetypes": [
    ]
}

Create a single archetype

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
name
required
string
description
string <= 10000 characters
isPublic
required
boolean

Whether to make this Archetype available to other team members

object

The attributes to set when using this Archetype

projects
Array of strings
environments
Array of strings

Limit this Archetype to specific environments. Omit or leave empty to apply to all environments.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "isPublic": true,
  • "attributes": {
    },
  • "projects": [
    ],
  • "environments": [
    ]
}

Response samples

Content type
application/json
{
  • "archetype": {
    }
}

Get a single archetype

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/archetypes/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "archetype": {
    }
}

Update a single archetype

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
required
name
string
description
string <= 10000 characters
isPublic
boolean

Whether to make this Archetype available to other team members

object

The attributes to set when using this Archetype

projects
Array of strings
environments
Array of strings

Limit this Archetype to specific environments. Omit or leave empty to apply to all environments.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "isPublic": true,
  • "attributes": {
    },
  • "projects": [
    ],
  • "environments": [
    ]
}

Response samples

Content type
application/json
{
  • "archetype": {
    }
}

Deletes a single archetype

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/archetypes/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "string"
}

Queries

Retrieve queries used in experiments to calculate results.

Get a single query

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/queries/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "query": {
    }
}

Settings

Get the organization settings.

Get organization settings

Authorizations:
bearerAuthbasicAuth

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/settings' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "settings": {
    }
}

Attributes

Used when targeting feature flags and experiments.

Get the organization's attributes

Authorizations:
bearerAuthbasicAuth
query Parameters
projectId
string

Filter to attributes available in this project — includes org-wide attributes (no project restriction) and attributes explicitly scoped to this project.

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/attributes' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "attributes": [
    ]
}

Create a new attribute

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
property
required
string

The attribute property

datatype
required
string
Enum: "boolean" "string" "number" "secureString" "enum" "string[]" "number[]" "secureString[]"

The attribute datatype

description
string

The description of the new attribute

archived
boolean

The attribute is archived

hashAttribute
boolean

Shall the attribute be hashed

enum
string

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.

format
string
Enum: "" "version" "date" "isoCountryCode"

The attribute's format

projects
Array of strings
tags
Array of strings

Responses

Request samples

Content type
application/json
{
  • "property": "string",
  • "datatype": "boolean",
  • "description": "string",
  • "archived": true,
  • "hashAttribute": true,
  • "enum": "string",
  • "format": "",
  • "projects": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "attribute": {
    }
}

Update an attribute

Authorizations:
bearerAuthbasicAuth
path Parameters
property
required
string

The attribute property

Request Body schema: application/json
required
datatype
string
Enum: "boolean" "string" "number" "secureString" "enum" "string[]" "number[]" "secureString[]"

The attribute datatype

description
string

The description of the new attribute

archived
boolean

The attribute is archived

hashAttribute
boolean

Shall the attribute be hashed

enum
string

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.

format
string
Enum: "" "version" "date" "isoCountryCode"

The attribute's format

projects
Array of strings
tags
Array of strings

Responses

Request samples

Content type
application/json
{
  • "datatype": "boolean",
  • "description": "string",
  • "archived": true,
  • "hashAttribute": true,
  • "enum": "string",
  • "format": "",
  • "projects": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "attribute": {
    }
}

Deletes a single attribute

Authorizations:
bearerAuthbasicAuth
path Parameters
property
required
string

The attribute property

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/attributes/abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedProperty": "string"
}

Usage

Usage information for metrics in experiments.

Get metric usage across experiments

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.

Authorizations:
bearerAuthbasicAuth
query Parameters
ids
required
string

List of comma-separated metric IDs (both fact and legacy) to get usage for, e.g. ids=met_123,fact_456

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/usage/metrics' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "metricUsage": [
    ]
}

Meta

Server metadata, including the running build's version and commit for version-skew checks.

Get the GrowthBook server version and build info

Authorizations:
bearerAuthbasicAuth

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/version' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "version": "string",
  • "commit": "string",
  • "date": "string"
}

Contextual Bandits

Get current Contextual Bandit leaf weights and latest event

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The Contextual Bandit id

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/contextual-bandits/{id}/current' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "currentLeafWeights": [
    ],
  • "latestEvent": {
    }
}

List Contextual Bandit snapshots

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The Contextual Bandit id

query Parameters
limit
integer ( 0 .. 100 ]

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/contextual-bandits/{id}/snapshots' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "snapshots": [
    ]
}

Get a single Contextual Bandit snapshot

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The Contextual Bandit id

snapshotId
required
string

The snapshot id

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/contextual-bandits/{id}/snapshots/{snapshotId}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "snapshot": {
    }
}

List Contextual Bandit weight-update events

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The Contextual Bandit id

query Parameters
limit
integer ( 0 .. 100 ]

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/contextual-bandits/{id}/events' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "events": [
    ]
}

Get a single Contextual Bandit weight-update event

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The Contextual Bandit id

eventId
required
string

The event id

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/contextual-bandits/{id}/events/{eventId}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "event": {
    }
}

Get latest Contextual Bandit results

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 SRM of the most recent 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 table.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The Contextual Bandit id

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/contextual-bandits/{id}/results' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "contextualBanditSnapshot": {
    },
  • "overallWeights": [
    ],
  • "results": {
    },
  • "latest": {
    }
}

Get features linked to a Contextual Bandit

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.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The Contextual Bandit id

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/contextual-bandits/{id}/linked-features' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "linkedFeatures": [
    ],
  • "environments": [
    ]
}

Unlink a feature from a Contextual Bandit

Detaches a feature from this contextual bandit by removing it from the bandit's linked-feature list and cancelling any queued draft auto-publish. The feature's contextual-bandit-ref rule itself is left untouched.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The Contextual Bandit id

featureId
required
string

The linked feature id

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/contextual-bandits/{id}/linked-feature/{featureId}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{ }

Get a single contextualBandit

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/contextual-bandits/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "contextualBandit": {
    }
}

Update a single contextualBandit

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string
description
string
project
string
owner
string

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.

tags
Array of strings
trackingKey
string
hashAttribute
string
Array of objects
datasource
string
contextualBanditQueryId
string
contextualAttributes
Array of strings
decisionMetric
string
minUsersPerLeaf
integer > 0
maxLeaves
integer > 0
scheduleValue
number
scheduleUnit
string
Enum: "days" "hours"
burnInValue
number
burnInUnit
string
Enum: "days" "hours"
number or null
string or null
archived
boolean
status
string
Enum: "draft" "running" "stopped"
coverage
number [ 0 .. 1 ]
condition
string
Array of objects
Array of objects
seed
string
Array of objects

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "project": "string",
  • "owner": "string",
  • "tags": [
    ],
  • "trackingKey": "string",
  • "hashAttribute": "string",
  • "variations": [
    ],
  • "datasource": "string",
  • "contextualBanditQueryId": "string",
  • "contextualAttributes": [
    ],
  • "decisionMetric": "string",
  • "minUsersPerLeaf": 0,
  • "maxLeaves": 0,
  • "scheduleValue": 0,
  • "scheduleUnit": "days",
  • "burnInValue": 0,
  • "burnInUnit": "days",
  • "conversionWindowValue": 0,
  • "conversionWindowUnit": "hours",
  • "archived": true,
  • "status": "draft",
  • "coverage": 1,
  • "condition": "string",
  • "savedGroups": [
    ],
  • "prerequisites": [
    ],
  • "seed": "string",
  • "variationWeights": [
    ]
}

Response samples

Content type
application/json
{
  • "contextualBandit": {
    }
}

Create a single contextualBandit

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
name
required
string
description
string
project
string
owner
string

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.

tags
Array of strings
trackingKey
required
string
hashAttribute
string
decisionMetric
required
string
required
Array of objects
datasource
required
string
contextualBanditQueryId
required
string
contextualAttributes
required
Array of strings
minUsersPerLeaf
integer > 0
maxLeaves
integer > 0
scheduleValue
number
scheduleUnit
string
Enum: "days" "hours"
burnInValue
number
burnInUnit
string
Enum: "days" "hours"
conversionWindowValue
number
conversionWindowUnit
string
Enum: "hours" "days"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "project": "string",
  • "owner": "string",
  • "tags": [
    ],
  • "trackingKey": "string",
  • "hashAttribute": "string",
  • "decisionMetric": "string",
  • "variations": [
    ],
  • "datasource": "string",
  • "contextualBanditQueryId": "string",
  • "contextualAttributes": [
    ],
  • "minUsersPerLeaf": 0,
  • "maxLeaves": 0,
  • "scheduleValue": 0,
  • "scheduleUnit": "days",
  • "burnInValue": 0,
  • "burnInUnit": "days",
  • "conversionWindowValue": 0,
  • "conversionWindowUnit": "hours"
}

Response samples

Content type
application/json
{
  • "contextualBandit": {
    }
}

Get all contextualBandits

Authorizations:
bearerAuthbasicAuth
query Parameters
projectId
string
datasourceId
string
trackingKey
string

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/contextual-bandits' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "contextualBandits": [
    ]
}

Start a Contextual Bandit

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
optional
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "contextualBandit": {
    }
}

Stop a Contextual Bandit

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
optional
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "contextualBandit": {
    }
}

Trigger a Contextual Bandit snapshot refresh

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
optional
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "snapshotId": "string",
  • "cbeId": "string"
}

Dashboards

Get a single dashboard

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/dashboards/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "dashboard": {
    }
}

Delete a single dashboard

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/dashboards/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "string"
}

Update a single dashboard

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
title
string

The display name of the Dashboard

editLevel
string
Enum: "published" "private"

Dashboards that are "published" are editable by organization members with appropriate permissions

shareLevel
string
Enum: "published" "private"

General Dashboards only. Dashboards that are "published" are viewable by organization members with appropriate permissions

enableAutoUpdates
boolean

If enabled for a General Dashboard, also requires an updateSchedule

object or object

General Dashboards only. Experiment Dashboards update based on the parent experiment instead

projects
Array of strings

General Dashboards only, Experiment Dashboards use the experiment's projects

object
Array of (object or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects) or (object or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects)

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "editLevel": "published",
  • "shareLevel": "published",
  • "enableAutoUpdates": true,
  • "updateSchedule": {
    },
  • "projects": [
    ],
  • "globalControls": {
    },
  • "blocks": [
    ]
}

Response samples

Content type
application/json
{
  • "dashboard": {
    }
}

Create a single dashboard

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
title
required
string

The display name of the Dashboard

editLevel
required
string
Enum: "published" "private"

Dashboards that are "published" are editable by organization members with appropriate permissions

shareLevel
required
string
Enum: "published" "private"

General Dashboards only. Dashboards that are "published" are viewable by organization members with appropriate permissions

enableAutoUpdates
required
boolean

If enabled for a General Dashboard, also requires an updateSchedule

object or object

General Dashboards only. Experiment Dashboards update based on the parent experiment instead

experimentId
string

The parent experiment for an Experiment Dashboard, or undefined for a general dashboard

projects
Array of strings

General Dashboards only, Experiment Dashboards use the experiment's projects

object
required
Array of objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "editLevel": "published",
  • "shareLevel": "published",
  • "enableAutoUpdates": true,
  • "updateSchedule": {
    },
  • "experimentId": "string",
  • "projects": [
    ],
  • "globalControls": {
    },
  • "blocks": [
    ]
}

Response samples

Content type
application/json
{
  • "dashboard": {
    }
}

Get all dashboards

Authorizations:
bearerAuthbasicAuth

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/dashboards' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "dashboards": [
    ]
}

Get all dashboards for an experiment

Authorizations:
bearerAuthbasicAuth
path Parameters
experimentId
required
string

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/dashboards/by-experiment/{experimentId}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "dashboards": [
    ]
}

Contextual Bandit Queries

Get a single contextualBanditQuery

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/contextual-bandit-queries/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "contextualBanditQuery": {
    }
}

Delete a single contextualBanditQuery

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/contextual-bandit-queries/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "string"
}

Update a single contextualBanditQuery

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
owner
string

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.

name
string
description
string
userIdType
string
query
string
targetingAttributeColumns
Array of strings

Responses

Request samples

Content type
application/json
{
  • "owner": "string",
  • "name": "string",
  • "description": "string",
  • "userIdType": "string",
  • "query": "string",
  • "targetingAttributeColumns": [
    ]
}

Response samples

Content type
application/json
{
  • "contextualBanditQuery": {
    }
}

Create a single contextualBanditQuery

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
owner
string

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 user associated with the request's Personal Access Token (PAT), if one is being used.

datasourceId
required
string
name
required
string
description
string
userIdType
required
string
query
required
string
targetingAttributeColumns
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "owner": "string",
  • "datasourceId": "string",
  • "name": "string",
  • "description": "string",
  • "userIdType": "string",
  • "query": "string",
  • "targetingAttributeColumns": [
    ]
}

Response samples

Content type
application/json
{
  • "contextualBanditQuery": {
    }
}

Get all contextualBanditQueries

Authorizations:
bearerAuthbasicAuth
query Parameters
datasourceId
string

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/contextual-bandit-queries' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "contextualBanditQueries": [
    ]
}

Custom Fields

Create a single customField

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
id
required
string non-empty

The unique key for the custom field

name
required
string

The display name of the custom field

description
string
placeholder
string
string or number or boolean or string or string or Array of strings or Array of numbers or Array of booleans or Array of strings or Array of strings
type
required
string
Enum: "text" "textarea" "markdown" "enum" "multiselect" "url" "number" "boolean" "date" "datetime"

The type of value this custom field will take

values
string
required
required
boolean
projects
Array of strings
sections
required
Array of strings
Items Enum: "feature" "experiment"

What types of objects this custom field is applicable to (feature, experiment)

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "placeholder": "string",
  • "defaultValue": "string",
  • "type": "text",
  • "values": "string",
  • "required": true,
  • "projects": [
    ],
  • "sections": [
    ]
}

Response samples

Content type
application/json
{
  • "customField": {
    }
}

Get all custom fields

Authorizations:
bearerAuthbasicAuth
query Parameters
projectId
string

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/custom-fields' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
[
  • {
    }
]

Delete a single customField

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
query Parameters
index
string

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/custom-fields/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "string"
}

Get a single customField

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/custom-fields/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "customField": {
    }
}

Update a single customField

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string

The display name of the custom field

description
string
placeholder
string
string or number or boolean or string or string or Array of strings or Array of numbers or Array of booleans or Array of strings or Array of strings
values
string
required
boolean
projects
Array of strings
sections
Array of strings
Items Enum: "feature" "experiment"

What types of objects this custom field is applicable to (feature, experiment)

active
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "placeholder": "string",
  • "defaultValue": "string",
  • "values": "string",
  • "required": true,
  • "projects": [
    ],
  • "sections": [
    ],
  • "active": true
}

Response samples

Content type
application/json
{
  • "customField": {
    }
}

Metric Groups

Get a single metricGroup

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/metric-groups/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "metricGroup": {
    }
}

Delete a single metricGroup

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/metric-groups/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "string"
}

Update a single metricGroup

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string
description
string <= 10000 characters
tags
Array of strings
projects
Array of strings
metrics
Array of strings
datasource
string
owner
string

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.

archived
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "tags": [
    ],
  • "projects": [
    ],
  • "metrics": [
    ],
  • "datasource": "string",
  • "owner": "string",
  • "archived": true
}

Response samples

Content type
application/json
{
  • "metricGroup": {
    }
}

Create a single metricGroup

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
name
required
string
description
required
string <= 10000 characters
tags
Array of strings
projects
required
Array of strings
metrics
required
Array of strings
datasource
required
string
owner
string

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.

archived
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "tags": [
    ],
  • "projects": [
    ],
  • "metrics": [
    ],
  • "datasource": "string",
  • "owner": "string",
  • "archived": true
}

Response samples

Content type
application/json
{
  • "metricGroup": {
    }
}

Get all metricGroups

Authorizations:
bearerAuthbasicAuth

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/metric-groups' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "metricGroups": [
    ]
}

Teams

Get a single team

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/teams/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "team": {
    }
}

Update a single team

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string
createdBy
string
description
string
role
string

The global role for members of this team

limitAccessByEnvironment
boolean
environments
Array of strings

An empty array means 'all environments'

Array of objects
object
defaultProject
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "createdBy": "string",
  • "description": "string",
  • "role": "string",
  • "limitAccessByEnvironment": true,
  • "environments": [
    ],
  • "projectRoles": [
    ],
  • "managedBy": {
    },
  • "defaultProject": "string"
}

Response samples

Content type
application/json
{
  • "team": {
    }
}

Delete a single team

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
query Parameters
deleteMembers
string

When 'true', enables deleting a team that contains members

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/teams/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "string"
}

Create a single team

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
name
required
string
createdBy
string
description
required
string
role
required
string

The global role for members of this team

limitAccessByEnvironment
boolean
environments
Array of strings

An empty array means 'all environments'

Array of objects
object
defaultProject
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "createdBy": "string",
  • "description": "string",
  • "role": "string",
  • "limitAccessByEnvironment": true,
  • "environments": [
    ],
  • "projectRoles": [
    ],
  • "managedBy": {
    },
  • "defaultProject": "string"
}

Response samples

Content type
application/json
{
  • "team": {
    }
}

Get all teams

Authorizations:
bearerAuthbasicAuth

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/teams' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "teams": [
    ]
}

Add members to team

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
members
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "members": [
    ]
}

Response samples

Content type
application/json
{
  • "status": 0
}

Remove members from team

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
members
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "members": [
    ]
}

Response samples

Content type
application/json
{
  • "status": 0
}

Experiment Templates

Get a single experimentTemplate

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/experiment-templates/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "experimentTemplate": {
    }
}

Delete a single experimentTemplate

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/experiment-templates/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "string"
}

Update a single experimentTemplate

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
project
string
object
type
string
Value: "standard"
hypothesis
string
description
string <= 10000 characters
tags
Array of strings
object
datasource
string
exposureQueryId
string
hashAttribute
string
fallbackAttribute
string
disableStickyBucketing
boolean
goalMetrics
Array of strings
secondaryMetrics
Array of strings
guardrailMetrics
Array of strings
activationMetric
string
statsEngine
string
Enum: "bayesian" "frequentist"
segment
string
skipPartialData
boolean
object
Array of objects

Responses

Request samples

Content type
application/json
{
  • "project": "string",
  • "templateMetadata": {
    },
  • "type": "standard",
  • "hypothesis": "string",
  • "description": "string",
  • "tags": [
    ],
  • "customFields": {
    },
  • "datasource": "string",
  • "exposureQueryId": "string",
  • "hashAttribute": "string",
  • "fallbackAttribute": "string",
  • "disableStickyBucketing": true,
  • "goalMetrics": [
    ],
  • "secondaryMetrics": [
    ],
  • "guardrailMetrics": [
    ],
  • "activationMetric": "string",
  • "statsEngine": "bayesian",
  • "segment": "string",
  • "skipPartialData": true,
  • "targeting": {
    },
  • "customMetricSlices": [
    ]
}

Response samples

Content type
application/json
{
  • "experimentTemplate": {
    }
}

Create a single experimentTemplate

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
project
string
required
object
type
required
string
Value: "standard"
hypothesis
string
description
string <= 10000 characters
tags
Array of strings
object
datasource
required
string
exposureQueryId
required
string
hashAttribute
string
fallbackAttribute
string
disableStickyBucketing
boolean
goalMetrics
Array of strings
secondaryMetrics
Array of strings
guardrailMetrics
Array of strings
activationMetric
string
statsEngine
required
string
Enum: "bayesian" "frequentist"
segment
string
skipPartialData
boolean
required
object
Array of objects

Responses

Request samples

Content type
application/json
{
  • "project": "string",
  • "templateMetadata": {
    },
  • "type": "standard",
  • "hypothesis": "string",
  • "description": "string",
  • "tags": [
    ],
  • "customFields": {
    },
  • "datasource": "string",
  • "exposureQueryId": "string",
  • "hashAttribute": "string",
  • "fallbackAttribute": "string",
  • "disableStickyBucketing": true,
  • "goalMetrics": [
    ],
  • "secondaryMetrics": [
    ],
  • "guardrailMetrics": [
    ],
  • "activationMetric": "string",
  • "statsEngine": "bayesian",
  • "segment": "string",
  • "skipPartialData": true,
  • "targeting": {
    },
  • "customMetricSlices": [
    ]
}

Response samples

Content type
application/json
{
  • "experimentTemplate": {
    }
}

Get all experimentTemplates

Authorizations:
bearerAuthbasicAuth
query Parameters
projectId
string

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/experiment-templates' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "experimentTemplates": [
    ]
}

Bulk create or update experiment templates

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
required
Array of objects
Array
id
required
string
required
object

Responses

Request samples

Content type
application/json
{
  • "templates": [
    ]
}

Response samples

Content type
application/json
{
  • "added": 0,
  • "updated": 0
}

Analytics Explorations

Create a Metric based visualization

Authorizations:
bearerAuthbasicAuth
query Parameters
cache
string
Enum: "preferred" "required" "never"

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

Request Body schema: application/json
required
datasource
required
string

ID of the datasource to query

required
Array of objects or objects or objects or objects
chartType
required
string
Enum: "line" "area" "timeseries-table" "table" "bar" "stackedBar" "horizontalBar" "stackedHorizontalBar" "bigNumber"
required
object
showAs
string
Enum: "total" "per_unit"
type
required
string
Value: "metric"
required
object

Responses

Request samples

Content type
application/json
{
  • "datasource": "string",
  • "dimensions": [
    ],
  • "chartType": "line",
  • "dateRange": {
    },
  • "showAs": "total",
  • "type": "metric",
  • "dataset": {
    }
}

Response samples

Content type
application/json
{
  • "exploration": {
    },
  • "query": {
    },
  • "explorationUrl": "string",
  • "message": "string"
}

Run a Fact Table based visualization

Authorizations:
bearerAuthbasicAuth
query Parameters
cache
string
Enum: "preferred" "required" "never"

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

Request Body schema: application/json
required
datasource
required
string

ID of the datasource to query

required
Array of objects or objects or objects or objects
chartType
required
string
Enum: "line" "area" "timeseries-table" "table" "bar" "stackedBar" "horizontalBar" "stackedHorizontalBar" "bigNumber"
required
object
showAs
string
Enum: "total" "per_unit"
type
required
string
Value: "fact_table"
required
object

Responses

Request samples

Content type
application/json
{
  • "datasource": "string",
  • "dimensions": [
    ],
  • "chartType": "line",
  • "dateRange": {
    },
  • "showAs": "total",
  • "type": "fact_table",
  • "dataset": {
    }
}

Response samples

Content type
application/json
{
  • "exploration": {
    },
  • "query": {
    },
  • "explorationUrl": "string",
  • "message": "string"
}

Create a Data Source based visualization

Authorizations:
bearerAuthbasicAuth
query Parameters
cache
string
Enum: "preferred" "required" "never"

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

Request Body schema: application/json
required
datasource
required
string

ID of the datasource to query

required
Array of objects or objects or objects or objects
chartType
required
string
Enum: "line" "area" "timeseries-table" "table" "bar" "stackedBar" "horizontalBar" "stackedHorizontalBar" "bigNumber"
required
object
showAs
string
Enum: "total" "per_unit"
type
required
string
Value: "data_source"
required
object

Responses

Request samples

Content type
application/json
{
  • "datasource": "string",
  • "dimensions": [
    ],
  • "chartType": "line",
  • "dateRange": {
    },
  • "showAs": "total",
  • "type": "data_source",
  • "dataset": {
    }
}

Response samples

Content type
application/json
{
  • "exploration": {
    },
  • "query": {
    },
  • "explorationUrl": "string",
  • "message": "string"
}

Run a Funnel based visualization

Authorizations:
bearerAuthbasicAuth
query Parameters
cache
string
Enum: "preferred" "required" "never"

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

Request Body schema: application/json
required
datasource
required
string

ID of the datasource to query

required
Array of objects or objects or objects or objects
chartType
required
string
Enum: "line" "area" "timeseries-table" "table" "bar" "stackedBar" "horizontalBar" "stackedHorizontalBar" "bigNumber"
required
object
showAs
string
Enum: "total" "per_unit"
type
required
string
Value: "funnel"
required
object

Responses

Request samples

Content type
application/json
{
  • "datasource": "string",
  • "dimensions": [
    ],
  • "chartType": "line",
  • "dateRange": {
    },
  • "showAs": "total",
  • "type": "funnel",
  • "dataset": {
    }
}

Response samples

Content type
application/json
{
  • "exploration": {
    },
  • "query": {
    },
  • "explorationUrl": "string",
  • "message": "string"
}

Ramp Schedule Templates

Reusable step configurations for ramp schedules.

Get a single rampScheduleTemplate

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/ramp-schedule-templates/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "rampScheduleTemplate": {
    }
}

Delete a single rampScheduleTemplate

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X DELETE 'https://api.growthbook.io/api/v1/ramp-schedule-templates/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "deletedId": "string"
}

Update a single rampScheduleTemplate

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Request Body schema: application/json
required
name
string
Array of objects
object
official
boolean
object or null
object
order
number

Display order within the org (lower sorts first).

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "steps": [
    ],
  • "endPatch": {
    },
  • "official": true,
  • "monitoringConfig": {
    },
  • "lockdownConfig": {
    },
  • "order": 0
}

Response samples

Content type
application/json
{
  • "rampScheduleTemplate": {
    }
}

Create a single rampScheduleTemplate

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
required
name
required
string
required
Array of objects
object
official
boolean
object or null
object
order
number

Display order within the org (lower sorts first). Omit to append to the end.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "steps": [
    ],
  • "endPatch": {
    },
  • "official": true,
  • "monitoringConfig": {
    },
  • "lockdownConfig": {
    },
  • "order": 0
}

Response samples

Content type
application/json
{
  • "rampScheduleTemplate": {
    }
}

Get all rampScheduleTemplates

Authorizations:
bearerAuthbasicAuth

Responses

Request samples 

curl -X GET 'https://api.growthbook.io/api/v1/ramp-schedule-templates' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response samples

Content type
application/json
{
  • "rampScheduleTemplates": [
    ]
}

Aggregated Fact Table

idType
required
string

The id type this aggregated table is keyed by

status
required
string
Enum: "running" "error" "pending" "active"

Materialization status: pending (not yet built), running (a refresh is in progress), active (materialized and queryable), or error (the last run failed).

required
string or null

Fully-qualified warehouse table name, or null if it has not been created yet

required
string or null

Earliest event date covered by the materialized data

required
string or null

Latest event date covered by the materialized data

required
string or null

Event-time high-water mark; the next incremental refresh appends events after this timestamp

required
string or null

Error message from the last failed run, if any

required
string or null

When the aggregation metadata was last updated

pendingRestate
required
boolean

Whether the next run will be forced to drop and rebuild the table instead of appending incrementally

required
string or null

Why a restate is pending, if pendingRestate is true

{
  • "idType": "string",
  • "status": "running",
  • "tableFullName": "string",
  • "firstEventDate": "2019-08-24T14:15:22Z",
  • "lastEventDate": "2019-08-24T14:15:22Z",
  • "lastMaxTimestamp": "2019-08-24T14:15:22Z",
  • "lastError": "string",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "pendingRestate": true,
  • "pendingRestateReason": "incomplete-write"
}

Analytics Exploration

id
required
string
dateCreated
required
string <date-time> ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[...
dateUpdated
required
string <date-time> ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[...
datasource
required
string
status
required
string
Enum: "running" "success" "error"
dateStart
required
string
dateEnd
required
string
string or null
required
object
required
object or object or object or object
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "datasource": "string",
  • "status": "running",
  • "dateStart": "string",
  • "dateEnd": "string",
  • "error": "string",
  • "result": {
    },
  • "config": {
    }
}

Archetype

id
required
string
dateCreated
required
string
dateUpdated
required
string
name
required
string
description
string <= 10000 characters
owner
required
string

The userId of the owner (or raw owner name/email for legacy records)

ownerEmail
string

The email address of the owner, when the owner can be resolved to a known user.

isPublic
required
boolean
required
object

The attributes to set when using this Archetype

projects
Array of strings
environments
Array of strings

Limit this Archetype to specific environments. Omit or leave empty to apply to all environments.

{
  • "id": "string",
  • "dateCreated": "string",
  • "dateUpdated": "string",
  • "name": "string",
  • "description": "string",
  • "owner": "string",
  • "ownerEmail": "string",
  • "isPublic": true,
  • "attributes": {
    },
  • "projects": [
    ],
  • "environments": [
    ]
}

Attribute

property
required
string
datatype
required
string
Enum: "boolean" "string" "number" "secureString" "enum" "string[]" "number[]" "secureString[]"
description
string
hashAttribute
boolean
archived
boolean
enum
string

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.

format
string
Enum: "" "version" "date" "isoCountryCode"
projects
Array of strings
tags
Array of strings
{
  • "property": "string",
  • "datatype": "boolean",
  • "description": "string",
  • "hashAttribute": true,
  • "archived": true,
  • "enum": "string",
  • "format": "",
  • "projects": [
    ],
  • "tags": [
    ]
}

Code Ref

organization
required
string

The organization name

dateUpdated
required
string <date-time>

When the code references were last updated

feature
required
string

Feature identifier

repo
required
string

Repository name

branch
required
string

Branch name

platform
string
Enum: "github" "gitlab" "bitbucket"

Source control platform

required
Array of objects
{
  • "organization": "string",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "feature": "string",
  • "repo": "string",
  • "branch": "string",
  • "platform": "github",
  • "refs": [
    ]
}

Config

id
required
string
key
required
string

Stable reference handle; used as @config:key in values

name
required
string
owner
string

The userId of the owner (or raw owner name/email for legacy records)

ownerEmail
string

The email address of the owner, when the owner can be resolved to a known user.

parent
string

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.

extends
Array of strings

Additional composition bases (config keys) 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.

object

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.

Array of objects

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).

object

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.

description
string <= 10000 characters
project
string

The project this config belongs to (empty = all projects)

archived
boolean
object

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.

extensible
boolean

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.

Array of objects

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.

locked
boolean

Whether this config is locked: frozen at a published revision. While locked no change can be published past that revision until it is unlocked (which requires the bypassApprovalChecks permission). Drafts may still be created and edited.

experimentGuard
boolean

Whether the experiment guard is enabled: publishing a change served to a running experiment soft-blocks (unless overridden with ignoreWarnings: true in the request body or bypassApprovalChecks). Turning it off requires bypassApprovalChecks.

object

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.

lockedBy
string

Id of the user who locked the config (when locked).

dateLocked
string <date-time>

When the config was locked (when locked).

dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
{
  • "id": "string",
  • "key": "string",
  • "name": "string",
  • "owner": "string",
  • "ownerEmail": "string",
  • "parent": "string",
  • "extends": [
    ],
  • "value": {
    },
  • "scopedOverrides": [
    ],
  • "scopedConfig": {
    },
  • "description": "string",
  • "project": "string",
  • "archived": true,
  • "schema": {
    },
  • "extensible": true,
  • "invariants": [
    ],
  • "locked": true,
  • "experimentGuard": true,
  • "lockedRevision": {
    },
  • "lockedBy": "string",
  • "dateLocked": "2019-08-24T14:15:22Z",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z"
}

Config Key Usage

familyKeys
required
Array of strings
required
Array of objects
{
  • "familyKeys": [
    ],
  • "implementations": [
    ]
}

Config Lineage

root
required
string

The key of the family root (the topmost ancestor).

target
required
string

The requested config's key.

ancestors
required
Array of strings

The target's ancestor keys, root-first, ending at its immediate parent.

descendants
required
Array of strings

Keys of every config that descends from the target.

required
Array of objects

Every config in the family (root plus all descendants), breadth-first.

{
  • "root": "string",
  • "target": "string",
  • "ancestors": [
    ],
  • "descendants": [
    ],
  • "nodes": [
    ]
}

Config References

required
Array of objects
required
Array of objects
{
  • "features": [
    ],
  • "constants": [
    ]
}

Config Revision

id
required
string
version
integer
title
string
status
required
string
Enum: "draft" "pending-review" "approved" "changes-requested" "merged" "discarded"
authorId
required
string
authorEmail
string
contributors
Array of strings
revertedFrom
string
required
Array of objects (ConfigRevisionReview)
required
Array of objects (ConfigRevisionActivityLogEntry)
object
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
required
object (Config)
required
object (Config)
required
Array of objects or objects or objects or objects or objects or objects
{
  • "id": "string",
  • "version": 0,
  • "title": "string",
  • "status": "draft",
  • "authorId": "string",
  • "authorEmail": "string",
  • "contributors": [
    ],
  • "revertedFrom": "string",
  • "reviews": [
    ],
  • "activityLog": [
    ],
  • "resolution": {
    },
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "baseConfig": {
    },
  • "proposedConfig": {
    },
  • "proposedChanges": [
    ]
}

Config Revision Activity Log Entry

id
required
string
userId
required
string
action
required
string
Enum: "created" "updated" "reviewed" "approved" "requested-changes" "commented" "review-requested" "review-retracted" "merged" "discarded" "reopened" "scheduled-publish" "scheduled-publish-updated" "scheduled-publish-canceled"
string or null
Array of objects or objects or objects or objects or objects or objects
targetSnapshot
any
dateCreated
required
string <date-time>
{
  • "id": "string",
  • "userId": "string",
  • "action": "created",
  • "description": "string",
  • "proposedChangesSnapshot": [
    ],
  • "targetSnapshot": null,
  • "dateCreated": "2019-08-24T14:15:22Z"
}

Config Revision Ref

entityType
required
string
Value: "config"
key
required
string

Config key.

version
required
integer

Revision version to publish.

{
  • "entityType": "config",
  • "key": "string",
  • "version": 0
}

Config Revision Review

id
required
string
userId
required
string
decision
required
string
Enum: "approve" "request-changes" "comment"
comment
string
stale
boolean

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.

dateCreated
required
string <date-time>
{
  • "id": "string",
  • "userId": "string",
  • "decision": "approve",
  • "comment": "string",
  • "stale": true,
  • "dateCreated": "2019-08-24T14:15:22Z"
}

Config Schema Export

required
ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) or ConfigSchemaSource (object) (ConfigSchemaSource)
effective
required
boolean

True when the schema includes inherited fields accumulated across the lineage; false when it is only this config's own fields.

additionalProperties
required
boolean

Whether the config family permits extra keys.

{
  • "schema": {
    },
  • "effective": true,
  • "additionalProperties": true
}

Config Schema Source

Any of
type
required
string
Value: "json-schema"
required
object

A JSON Schema document (an object).

{
  • "type": "rust",
  • "value": "string"
}

Config Schema Verify

inSync
required
boolean

True when the supplied schema is canonically identical to the config's stored schema.

fingerprint
required
string

Canonical fingerprint of the config's stored schema.

incomingFingerprint
required
string

Canonical fingerprint of the supplied schema.

object

Present only when inSync is false.

Array of objects

Supplied fields an ancestor config already owns ("base wins"). Subtract these from drift.contract adds when round-tripping a full effective schema.

Array of objects (ConfigSchemaWarning)
{
  • "inSync": true,
  • "fingerprint": "string",
  • "incomingFingerprint": "string",
  • "drift": {
    },
  • "ancestorOwnedFields": [
    ],
  • "warnings": [
    ]
}

Config Schema Warning

code
required
string
Enum: "dropped-declaration" "non-object-root" "unresolved-type" "unsupported-member" "redundant-declaration" "undeclared-rule-field"
message
required
string
path
string
{
  • "code": "dropped-declaration",
  • "message": "string",
  • "path": "string"
}

Constant

id
required
string
key
required
string

Stable reference handle; used as @const:key in values

name
required
string
type
required
string
Enum: "string" "json"
owner
string

The userId of the owner (or raw owner name/email for legacy records)

ownerEmail
string

The email address of the owner, when the owner can be resolved to a known user.

value
string

The default value (raw string for string constants, JSON-encoded for json constants)

object

Per-environment value overrides (environment id → value). Falls back to value when an environment is absent.

description
string <= 10000 characters
project
string

The project this constant belongs to (empty = all projects)

archived
boolean
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
{
  • "id": "string",
  • "key": "string",
  • "name": "string",
  • "type": "string",
  • "owner": "string",
  • "ownerEmail": "string",
  • "value": "string",
  • "environmentValues": {
    },
  • "description": "string",
  • "project": "string",
  • "archived": true,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z"
}

Constant References

required
Array of objects
required
Array of objects
{
  • "features": [
    ],
  • "constants": [
    ]
}

Constant Revision

id
required
string
version
integer
title
string
status
required
string
Enum: "draft" "pending-review" "approved" "changes-requested" "merged" "discarded"
authorId
required
string
authorEmail
string
contributors
Array of strings
revertedFrom
string
required
Array of objects (ConstantRevisionReview)
required
Array of objects (ConstantRevisionActivityLogEntry)
object
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
required
object (Constant)
required
object (Constant)
required
Array of objects or objects or objects or objects or objects or objects
{
  • "id": "string",
  • "version": 0,
  • "title": "string",
  • "status": "draft",
  • "authorId": "string",
  • "authorEmail": "string",
  • "contributors": [
    ],
  • "revertedFrom": "string",
  • "reviews": [
    ],
  • "activityLog": [
    ],
  • "resolution": {
    },
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "baseConstant": {
    },
  • "proposedConstant": {
    },
  • "proposedChanges": [
    ]
}

Constant Revision Activity Log Entry

id
required
string
userId
required
string
action
required
string
Enum: "created" "updated" "reviewed" "approved" "requested-changes" "commented" "review-requested" "review-retracted" "merged" "discarded" "reopened" "scheduled-publish" "scheduled-publish-updated" "scheduled-publish-canceled"
string or null
Array of objects or objects or objects or objects or objects or objects
targetSnapshot
any
dateCreated
required
string <date-time>
{
  • "id": "string",
  • "userId": "string",
  • "action": "created",
  • "description": "string",
  • "proposedChangesSnapshot": [
    ],
  • "targetSnapshot": null,
  • "dateCreated": "2019-08-24T14:15:22Z"
}

Constant Revision Ref

entityType
required
string
Value: "constant"
key
required
string

Constant key.

version
required
integer

Revision version to publish.

{
  • "entityType": "constant",
  • "key": "string",
  • "version": 0
}

Constant Revision Review

id
required
string
userId
required
string
decision
required
string
Enum: "approve" "request-changes" "comment"
comment
string
stale
boolean

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.

dateCreated
required
string <date-time>
{
  • "id": "string",
  • "userId": "string",
  • "decision": "approve",
  • "comment": "string",
  • "stale": true,
  • "dateCreated": "2019-08-24T14:15:22Z"
}

Contextual Bandit

id
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
name
required
string
description
string
project
string
owner
required
string

The userId of the owner (or raw owner name/email for legacy records)

ownerEmail
string

The email address of the owner, when the owner can be resolved to a known user.

tags
required
Array of strings
archived
required
boolean
status
required
string
Enum: "draft" "running" "stopped"
dateStarted
string <date-time>
dateStopped
string <date-time>
trackingKey
required
string
hashAttribute
required
string
required
Array of objects
datasource
required
string
contextualBanditQueryId
required
string
coverage
number [ 0 .. 1 ]
condition
string
Array of objects
Array of objects
seed
string
Array of objects
required
Array of objects
banditVersion
required
integer >= 0
contextualAttributes
required
Array of strings
decisionMetric
string
minUsersPerLeaf
required
integer > 0
maxLeaves
required
integer > 0
holdoutPercent
required
number [ 0 .. 0.5 ]
banditModelVersion
required
integer >= 0
scheduleValue
number
scheduleUnit
string
Enum: "days" "hours"
burnInValue
number
burnInUnit
string
Enum: "days" "hours"
number or null
string or null
stage
string
Enum: "explore" "exploit" "paused"
stageDateStarted
string <date-time>
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "description": "string",
  • "project": "string",
  • "owner": "string",
  • "ownerEmail": "string",
  • "tags": [
    ],
  • "archived": true,
  • "status": "draft",
  • "dateStarted": "2019-08-24T14:15:22Z",
  • "dateStopped": "2019-08-24T14:15:22Z",
  • "trackingKey": "string",
  • "hashAttribute": "string",
  • "variations": [
    ],
  • "datasource": "string",
  • "contextualBanditQueryId": "string",
  • "coverage": 1,
  • "condition": "string",
  • "savedGroups": [
    ],
  • "prerequisites": [
    ],
  • "seed": "string",
  • "variationWeights": [
    ],
  • "currentLeafWeights": [
    ],
  • "banditVersion": 0,
  • "contextualAttributes": [
    ],
  • "decisionMetric": "string",
  • "minUsersPerLeaf": 0,
  • "maxLeaves": 0,
  • "holdoutPercent": 0.5,
  • "banditModelVersion": 0,
  • "scheduleValue": 0,
  • "scheduleUnit": "days",
  • "burnInValue": 0,
  • "burnInUnit": "days",
  • "conversionWindowValue": 0,
  • "conversionWindowUnit": "hours",
  • "stage": "explore",
  • "stageDateStarted": "2019-08-24T14:15:22Z"
}

Contextual Bandit Query

id
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
owner
required
string

The userId of the owner (or raw owner name/email for legacy records)

ownerEmail
string

The email address of the owner, when the owner can be resolved to a known user.

datasourceId
required
string
name
required
string
description
string
userIdType
required
string
query
required
string
targetingAttributeColumns
required
Array of strings
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "owner": "string",
  • "ownerEmail": "string",
  • "datasourceId": "string",
  • "name": "string",
  • "description": "string",
  • "userIdType": "string",
  • "query": "string",
  • "targetingAttributeColumns": [
    ]
}

Custom Field

id
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
name
required
string
description
string
placeholder
string
string or number or boolean or string or string or Array of strings or Array of numbers or Array of booleans or Array of strings or Array of strings
type
required
string
Enum: "text" "textarea" "markdown" "enum" "multiselect" "url" "number" "boolean" "date" "datetime"
values
string
required
required
boolean
creator
string
projects
Array of strings
sections
required
Array of strings
Items Enum: "feature" "experiment"
active
boolean
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "description": "string",
  • "placeholder": "string",
  • "defaultValue": "string",
  • "type": "text",
  • "values": "string",
  • "required": true,
  • "creator": "string",
  • "projects": [
    ],
  • "sections": [
    ],
  • "active": true
}

Custom Hook

id
required
string
name
required
string
hook
required
string
Enum: "validateFeature" "validateFeatureRevision" "validateConfig" "validateConfigRevision" "validateExperiment"

Which save/publish event runs the hook (and which entity type it validates)

code
required
string

JavaScript function body executed in the sandbox. Throw an Error to block the save; call addWarning(msg) for a soft warning.

enabled
required
boolean
projects
required
Array of strings

Project ids the hook applies to (empty = all projects). Always empty for entity-scoped hooks.

entityType
string
Enum: "feature" "config" "experiment"

Set (with entityId) to scope the hook to a single resource.

entityId
string

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).

incrementalChangesOnly
boolean

When true, errors/warnings that already existed before the change being validated are suppressed

lastSuccess
string <date-time>
lastFailure
string <date-time>
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
{
  • "id": "string",
  • "name": "string",
  • "hook": "validateFeature",
  • "code": "string",
  • "enabled": true,
  • "projects": [
    ],
  • "entityType": "feature",
  • "entityId": "string",
  • "incrementalChangesOnly": true,
  • "lastSuccess": "2019-08-24T14:15:22Z",
  • "lastFailure": "2019-08-24T14:15:22Z",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z"
}

Dashboard

id
required
string
uid
required
string
organization
required
string
experimentId
string
isDefault
required
boolean
isDeleted
required
boolean
userId
required
string
editLevel
required
string
Enum: "published" "private"
shareLevel
required
string
Enum: "published" "private"
enableAutoUpdates
required
boolean
object or object
title
required
string
object
object
object
projects
Array of strings
nextUpdate
string <date-time>
lastUpdated
string <date-time>
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
required
Array of objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects or objects
{
  • "id": "string",
  • "uid": "string",
  • "organization": "string",
  • "experimentId": "string",
  • "isDefault": true,
  • "isDeleted": true,
  • "userId": "string",
  • "editLevel": "published",
  • "shareLevel": "published",
  • "enableAutoUpdates": true,
  • "updateSchedule": {
    },
  • "title": "string",
  • "globalControls": {
    },
  • "comparison": {
    },
  • "grid": {
    },
  • "projects": [
    ],
  • "nextUpdate": "2019-08-24T14:15:22Z",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "blocks": [
    ]
}

Data Source

id
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
type
required
string
name
required
string
description
required
string <= 10000 characters
projectIds
required
Array of strings
eventTracker
required
string
required
Array of objects
required
Array of objects
required
Array of objects
object
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "type": "string",
  • "name": "string",
  • "description": "string",
  • "projectIds": [
    ],
  • "eventTracker": "string",
  • "identifierTypes": [
    ],
  • "assignmentQueries": [
    ],
  • "identifierJoinQueries": [
    ],
  • "mixpanelSettings": {
    }
}

Dimension

id
required
string
dateCreated
required
string
dateUpdated
required
string
owner
required
string

The userId of the owner (or raw owner name/email for legacy records)

ownerEmail
string

The email address of the owner, when the owner can be resolved to a known user.

datasourceId
required
string
identifierType
required
string
name
required
string
description
string <= 10000 characters
query
required
string
managedBy
string
Enum: "" "api" "config"

Where this dimension must be managed from. If not set (empty string), it can be managed from anywhere.

{
  • "id": "string",
  • "dateCreated": "string",
  • "dateUpdated": "string",
  • "owner": "string",
  • "ownerEmail": "string",
  • "datasourceId": "string",
  • "identifierType": "string",
  • "name": "string",
  • "description": "string",
  • "query": "string",
  • "managedBy": ""
}

Environment

id
required
string
description
required
string
toggleOnList
required
boolean
defaultState
required
boolean
projects
required
Array of strings
parent
string
{
  • "id": "string",
  • "description": "string",
  • "toggleOnList": true,
  • "defaultState": true,
  • "projects": [
    ],
  • "parent": "string"
}

Event User

type
required
string
Enum: "dashboard" "api_key" "system"
id
string
name
string
email
string
{
  • "type": "dashboard",
  • "id": "string",
  • "name": "string",
  • "email": "string"
}

Experiment

id
required
string
trackingKey
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
name
required
string
type
required
string
Enum: "standard" "multi-armed-bandit" "holdout"
project
required
string
hypothesis
required
string
description
required
string <= 10000 characters
tags
required
Array of strings
owner
required
string

The userId of the owner (or raw owner name/email for legacy records)

ownerEmail
string

The email address of the owner, when the owner can be resolved to a known user.

archived
required
boolean
status
required
string
autoRefresh
required
boolean
hashAttribute
required
string
fallbackAttribute
string
required
1 (number) or 2 (number)
disableStickyBucketing
boolean
bucketVersion
number
minBucketVersion
number
required
Array of objects
required
Array of objects
required
object (ExperimentAnalysisSettings)
object
shareLevel
string
Enum: "public" "organization"
publicUrl
string
banditScheduleValue
number
banditScheduleUnit
string
Enum: "days" "hours"
banditBurnInValue
number
banditBurnInUnit
string
Enum: "days" "hours"
banditConversionWindowValue
number
banditConversionWindowUnit
string
Enum: "days" "hours"
linkedFeatures
Array of strings
hasVisualChangesets
boolean
hasURLRedirects
boolean
object
Array of objects

Custom slices that apply to ALL applicable metrics in the experiment

precomputedUnitDimensionIds
Array of strings <= 3 items
defaultDashboardId
string

ID of the default dashboard for this experiment.

templateId
string
object or null
object or null
{
  • "id": "string",
  • "trackingKey": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "type": "standard",
  • "project": "string",
  • "hypothesis": "string",
  • "description": "string",
  • "tags": [
    ],
  • "owner": "string",
  • "ownerEmail": "string",
  • "archived": true,
  • "status": "string",
  • "autoRefresh": true,
  • "hashAttribute": "string",
  • "fallbackAttribute": "string",
  • "hashVersion": 1,
  • "disableStickyBucketing": true,
  • "bucketVersion": 0,
  • "minBucketVersion": 0,
  • "variations": [
    ],
  • "phases": [
    ],
  • "settings": {
    },
  • "resultSummary": {
    },
  • "shareLevel": "public",
  • "publicUrl": "string",
  • "banditScheduleValue": 0,
  • "banditScheduleUnit": "days",
  • "banditBurnInValue": 0,
  • "banditBurnInUnit": "days",
  • "banditConversionWindowValue": 0,
  • "banditConversionWindowUnit": "days",
  • "linkedFeatures": [
    ],
  • "hasVisualChangesets": true,
  • "hasURLRedirects": true,
  • "customFields": {
    },
  • "customMetricSlices": [
    ],
  • "precomputedUnitDimensionIds": [
    ],
  • "defaultDashboardId": "string",
  • "templateId": "string",
  • "statusUpdateSchedule": {
    },
  • "nextScheduledStatusUpdate": {
    }
}

Experiment Rule

description
string
enabled
boolean
condition
string
Array of objects
Array of objects
allEnvironments
boolean

When true the rule applies to all environments. Defaults to false.

environments
Array of strings

Specific environment IDs this rule applies to. Used when allEnvironments is false.

type
required
string

Must be "experiment-ref" for an experiment rule.

Value: "experiment-ref"
experimentId
required
string

ID of the linked experiment.

required
Array of objects
sparse
boolean

JSON features only. When true, each variation value is a partial object merged onto the feature's default value instead of replacing it.

{
  • "description": "string",
  • "enabled": true,
  • "condition": "string",
  • "savedGroups": [
    ],
  • "prerequisites": [
    ],
  • "allEnvironments": true,
  • "environments": [
    ],
  • "type": "experiment-ref",
  • "experimentId": "string",
  • "variations": [
    ],
  • "sparse": true
}

Experiment Analysis Settings

datasourceId
required
string
assignmentQueryId
required
string
experimentId
required
string
segmentId
required
string
queryFilter
required
string
inProgressConversions
required
string
Enum: "include" "exclude"
attributionModel
required
string
Enum: "firstExposure" "experimentDuration" "lookbackOverride"

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.

object (LookbackOverride)

Controls the lookback override for the experiment. For type "window", value must be a non-negative number and valueUnit is required.

statsEngine
required
string
Enum: "bayesian" "frequentist"
regressionAdjustmentEnabled
boolean
sequentialTestingEnabled
boolean
sequentialTestingTuningParameter
number
boolean or null

When null, the organization default is used.

object (ExperimentDecisionFrameworkSettings)

Controls the decision framework and metric overrides for the experiment. Replaces the entire stored object on update (does not patch individual fields).

Array of objects (ExperimentMetricOverrideEntry)

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).

required
Array of objects (ExperimentMetric)
required
Array of objects (ExperimentMetric)
required
Array of objects (ExperimentMetric)
object (ExperimentMetric)
{
  • "datasourceId": "string",
  • "assignmentQueryId": "string",
  • "experimentId": "string",
  • "segmentId": "string",
  • "queryFilter": "string",
  • "inProgressConversions": "include",
  • "attributionModel": "firstExposure",
  • "lookbackOverride": {
    },
  • "statsEngine": "bayesian",
  • "regressionAdjustmentEnabled": true,
  • "sequentialTestingEnabled": true,
  • "sequentialTestingTuningParameter": 0,
  • "postStratificationEnabled": true,
  • "decisionFrameworkSettings": {
    },
  • "metricOverrides": [
    ],
  • "goals": [
    ],
  • "secondaryMetrics": [
    ],
  • "guardrails": [
    ],
  • "activationMetric": {
    }
}

Experiment Decision Framework Settings

decisionCriteriaId
string
Array of objects
{
  • "decisionCriteriaId": "string",
  • "decisionFrameworkMetricOverrides": [
    ]
}

Experiment Metric

metricId
required
string
required
object
{
  • "metricId": "string",
  • "overrides": {
    }
}

Experiment Metric Override Entry

id
required
string

ID of the metric to override settings for.

windowType
string
Enum: "conversion" "lookback" ""
windowHours
number
delayHours
number
properPriorOverride
boolean

Must be true for the override to take effect. If true, the other proper prior settings in this object will be used if present.

properPriorEnabled
boolean
properPriorMean
number
properPriorStdDev
number
regressionAdjustmentOverride
boolean

Must be true for the override to take effect. If true, the other regression adjustment settings in this object will be used if present.

regressionAdjustmentEnabled
boolean
regressionAdjustmentDays
number
{
  • "id": "string",
  • "windowType": "conversion",
  • "windowHours": 0,
  • "delayHours": 0,
  • "properPriorOverride": true,
  • "properPriorEnabled": true,
  • "properPriorMean": 0,
  • "properPriorStdDev": 0,
  • "regressionAdjustmentOverride": true,
  • "regressionAdjustmentEnabled": true,
  • "regressionAdjustmentDays": 0
}

Experiment Results

id
required
string
dateUpdated
required
string
experimentId
required
string
phase
required
string
dateStart
required
string
dateEnd
required
string
required
object
required
object (ExperimentAnalysisSettings)
queryIds
required
Array of strings
required
Array of objects
{
  • "id": "string",
  • "dateUpdated": "string",
  • "experimentId": "string",
  • "phase": "string",
  • "dateStart": "string",
  • "dateEnd": "string",
  • "dimension": {
    },
  • "settings": {
    },
  • "queryIds": [
    ],
  • "results": [
    ]
}

Experiment Snapshot

id
required
string
experiment
required
string
status
required
string
{
  • "id": "string",
  • "experiment": "string",
  • "status": "string"
}

Experiment Template

id
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
project
string
owner
required
string

The userId of the owner (or raw owner name/email for legacy records)

ownerEmail
string

The email address of the owner, when the owner can be resolved to a known user.

required
object
type
required
string
Value: "standard"
hypothesis
string
description
string <= 10000 characters
tags
Array of strings
object
datasource
required
string
exposureQueryId
required
string
hashAttribute
string
fallbackAttribute
string
disableStickyBucketing
boolean
goalMetrics
Array of strings
secondaryMetrics
Array of strings
guardrailMetrics
Array of strings
activationMetric
string
statsEngine
required
string
Enum: "bayesian" "frequentist"
segment
string
skipPartialData
boolean
required
object
Array of objects
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "project": "string",
  • "owner": "string",
  • "ownerEmail": "string",
  • "templateMetadata": {
    },
  • "type": "standard",
  • "hypothesis": "string",
  • "description": "string",
  • "tags": [
    ],
  • "customFields": {
    },
  • "datasource": "string",
  • "exposureQueryId": "string",
  • "hashAttribute": "string",
  • "fallbackAttribute": "string",
  • "disableStickyBucketing": true,
  • "goalMetrics": [
    ],
  • "secondaryMetrics": [
    ],
  • "guardrailMetrics": [
    ],
  • "activationMetric": "string",
  • "statsEngine": "bayesian",
  • "segment": "string",
  • "skipPartialData": true,
  • "targeting": {
    },
  • "customMetricSlices": [
    ]
}

Experiment With Enhanced Status

id
required
string
trackingKey
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
name
required
string
type
required
string
Enum: "standard" "multi-armed-bandit" "holdout"
project
required
string
hypothesis
required
string
description
required
string <= 10000 characters
tags
required
Array of strings
owner
required
string

The userId of the owner (or raw owner name/email for legacy records)

ownerEmail
string

The email address of the owner, when the owner can be resolved to a known user.

archived
required
boolean
status
required
string
autoRefresh
required
boolean
hashAttribute
required
string
fallbackAttribute
string
required
1 (number) or 2 (number)
disableStickyBucketing
boolean
bucketVersion
number
minBucketVersion
number
required
Array of objects
required
Array of objects
required
object (ExperimentAnalysisSettings)
object
shareLevel
string
Enum: "public" "organization"
publicUrl
string
banditScheduleValue
number
banditScheduleUnit
string
Enum: "days" "hours"
banditBurnInValue
number
banditBurnInUnit
string
Enum: "days" "hours"
banditConversionWindowValue
number
banditConversionWindowUnit
string
Enum: "days" "hours"
linkedFeatures
Array of strings
hasVisualChangesets
boolean
hasURLRedirects
boolean
object
Array of objects

Custom slices that apply to ALL applicable metrics in the experiment

precomputedUnitDimensionIds
Array of strings <= 3 items
defaultDashboardId
string

ID of the default dashboard for this experiment.

templateId
string
object or null
object or null
object
{
  • "id": "string",
  • "trackingKey": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "type": "standard",
  • "project": "string",
  • "hypothesis": "string",
  • "description": "string",
  • "tags": [
    ],
  • "owner": "string",
  • "ownerEmail": "string",
  • "archived": true,
  • "status": "string",
  • "autoRefresh": true,
  • "hashAttribute": "string",
  • "fallbackAttribute": "string",
  • "hashVersion": 1,
  • "disableStickyBucketing": true,
  • "bucketVersion": 0,
  • "minBucketVersion": 0,
  • "variations": [
    ],
  • "phases": [
    ],
  • "settings": {
    },
  • "resultSummary": {
    },
  • "shareLevel": "public",
  • "publicUrl": "string",
  • "banditScheduleValue": 0,
  • "banditScheduleUnit": "days",
  • "banditBurnInValue": 0,
  • "banditBurnInUnit": "days",
  • "banditConversionWindowValue": 0,
  • "banditConversionWindowUnit": "days",
  • "linkedFeatures": [
    ],
  • "hasVisualChangesets": true,
  • "hasURLRedirects": true,
  • "customFields": {
    },
  • "customMetricSlices": [
    ],
  • "precomputedUnitDimensionIds": [
    ],
  • "defaultDashboardId": "string",
  • "templateId": "string",
  • "statusUpdateSchedule": {
    },
  • "nextScheduledStatusUpdate": {
    },
  • "enhancedStatus": {
    }
}

Fact Metric

id
required
string
name
required
string
description
required
string <= 10000 characters
owner
required
string

The userId of the owner (or raw owner name/email for legacy records)

ownerEmail
string

The email address of the owner, when the owner can be resolved to a known user.

projects
required
Array of strings
tags
required
Array of strings
datasource
required
string
metricType
required
string
Enum: "proportion" "retention" "mean" "quantile" "ratio" "dailyParticipation"
required
object
object
inverse
required
boolean

Set to true for things like Bounce Rate, where you want the metric to decrease

object

Controls the settings for quantile metrics (mandatory if metricType is "quantile")

required
object

Controls how outliers are handled

required
object

Controls the conversion window for the metric

required
object

Controls the bayesian prior for the metric

required
object

Controls the regression adjustment (CUPED) settings for the metric

riskThresholdSuccess
required
number
riskThresholdDanger
required
number
displayAsPercentage
boolean

If true and the metric is a ratio metric, variation means will be displayed as a percentage

minPercentChange
required
number
maxPercentChange
required
number
minSampleSize
required
number
targetMDE
required
number
managedBy
required
string
Enum: "" "api" "admin"

Where this fact metric must be managed from. If not set (empty string), it can be managed from anywhere.

dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
archived
boolean
metricAutoSlices
Array of strings

Array of slice column names that will be automatically included in metric analysis. This is an enterprise feature.

{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "owner": "string",
  • "ownerEmail": "string",
  • "projects": [
    ],
  • "tags": [
    ],
  • "datasource": "string",
  • "metricType": "proportion",
  • "numerator": {
    },
  • "denominator": {
    },
  • "inverse": true,
  • "quantileSettings": {
    },
  • "cappingSettings": {
    },
  • "windowSettings": {
    },
  • "priorSettings": {
    },
  • "regressionAdjustmentSettings": {
    },
  • "riskThresholdSuccess": 0,
  • "riskThresholdDanger": 0,
  • "displayAsPercentage": true,
  • "minPercentChange": 0,
  • "maxPercentChange": 0,
  • "minSampleSize": 0,
  • "targetMDE": 0,
  • "managedBy": "",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "archived": true,
  • "metricAutoSlices": [
    ]
}

Fact Table

id
required
string
name
required
string
description
required
string <= 10000 characters
owner
required
string

The userId of the owner (or raw owner name/email for legacy records)

ownerEmail
string

The email address of the owner, when the owner can be resolved to a known user.

projects
required
Array of strings
tags
required
Array of strings
datasource
required
string
userIdTypes
required
Array of strings
object

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.

sql
required
string
eventName
string

The event name used in SQL template variables

Array of objects (FactTableColumn)

Array of column definitions for this fact table

string or null

Error message if there was an issue parsing the SQL schema

archived
boolean
managedBy
required
string
Enum: "" "api" "admin"

Where this fact table must be managed from. If not set (empty string), it can be managed from anywhere.

dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "owner": "string",
  • "ownerEmail": "string",
  • "projects": [
    ],
  • "tags": [
    ],
  • "datasource": "string",
  • "userIdTypes": [
    ],
  • "aggregatedFactTableSettings": {
    },
  • "sql": "string",
  • "eventName": "string",
  • "columns": [
    ],
  • "columnsError": "string",
  • "archived": true,
  • "managedBy": "",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z"
}

Fact Table Column

column
required
string

The actual column name in the database/SQL query

datatype
required
string
Enum: "number" "string" "date" "boolean" "json" "binary" "other" ""
numberFormat
string
Enum: "" "currency" "time:seconds" "memory:bytes" "memory:kilobytes"
object

For JSON columns, defines the structure of nested fields

name
string

Display name for the column (can be different from the actual column name)

description
string <= 10000 characters
alwaysInlineFilter
boolean
Default: false

Whether this column should always be included as an inline filter in queries

deleted
boolean
Default: false
isAutoSliceColumn
boolean
Default: false

Whether this column can be used for auto slice analysis. This is an enterprise feature.

autoSlices
Array of strings

Specific slices to automatically analyze for this column.

lockedAutoSlices
Array of strings

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.

dateCreated
string <date-time>
dateUpdated
string <date-time>
{
  • "column": "string",
  • "datatype": "number",
  • "numberFormat": "",
  • "jsonFields": {
    },
  • "name": "string",
  • "description": "string",
  • "alwaysInlineFilter": false,
  • "deleted": false,
  • "isAutoSliceColumn": false,
  • "autoSlices": [
    ],
  • "lockedAutoSlices": [
    ],
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z"
}

Fact Table Filter

id
required
string
name
required
string
description
required
string <= 10000 characters
value
required
string
managedBy
required
string
Enum: "" "api"

Where this fact table filter must be managed from. If not set (empty string), it can be managed from anywhere.

dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "value": "string",
  • "managedBy": "",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z"
}

Feature Base Rule

description
required
string <= 10000 characters
condition
string
id
required
string
enabled
required
boolean
Array of objects (ScheduleRule)

Simple time-based on/off schedule for this rule

scheduleType
string
Enum: "none" "schedule" "ramp"

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
rampScheduleId
string

ID of the active RampSchedule document controlling this rule. Present when scheduleType is ramp and a live schedule exists.

Array of objects
Array of objects
allProjects
boolean

When true (the default) the rule applies to every project the feature is delivered to. When false the rule is limited to projects.

projects
Array of strings

Project IDs this rule is scoped to when allProjects is false. An empty array scopes the rule to no project.

{
  • "description": "string",
  • "condition": "string",
  • "id": "string",
  • "enabled": true,
  • "scheduleRules": [
    ],
  • "scheduleType": "none",
  • "rampScheduleId": "string",
  • "savedGroupTargeting": [
    ],
  • "prerequisites": [
    ],
  • "allProjects": true,
  • "projects": [
    ]
}

Feature Contextual Bandit Ref Rule

description
required
string <= 10000 characters
condition
string
id
required
string
enabled
required
boolean
Array of objects (ScheduleRule)

Simple time-based on/off schedule for this rule

scheduleType
string
Enum: "none" "schedule" "ramp"

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
rampScheduleId
string

ID of the active RampSchedule document controlling this rule. Present when scheduleType is ramp and a live schedule exists.

Array of objects
Array of objects
allProjects
boolean

When true (the default) the rule applies to every project the feature is delivered to. When false the rule is limited to projects.

projects
Array of strings

Project IDs this rule is scoped to when allProjects is false. An empty array scopes the rule to no project.

type
required
string
Value: "contextual-bandit-ref"
required
Array of objects
contextualBanditId
required
string
{
  • "description": "string",
  • "condition": "string",
  • "id": "string",
  • "enabled": true,
  • "scheduleRules": [
    ],
  • "scheduleType": "none",
  • "rampScheduleId": "string",
  • "savedGroupTargeting": [
    ],
  • "prerequisites": [
    ],
  • "allProjects": true,
  • "projects": [
    ],
  • "type": "contextual-bandit-ref",
  • "variations": [
    ],
  • "contextualBanditId": "string"
}

Feature Definition

required
string or number or Array of any or object or null
Array of objects
{
  • "defaultValue": "string",
  • "rules": [
    ]
}

Feature Environment V1

enabled
required
boolean
defaultValue
required
string
required
Array of FeatureForceRule (object) or FeatureRolloutRule (object) or FeatureExperimentRule (object) or FeatureExperimentRefRule (object) or FeatureContextualBanditRefRule (object) or FeatureSafeRolloutRule (object) (FeatureRuleV1)
definition
string

A JSON stringified FeatureDefinition

object
{
  • "enabled": true,
  • "defaultValue": "string",
  • "rules": [
    ],
  • "definition": "string",
  • "draft": {
    }
}

Feature Environment V2

enabled
required
boolean
defaultValue
required
string
definition
string

A JSON stringified FeatureDefinition

{
  • "enabled": true,
  • "defaultValue": "string",
  • "definition": "string"
}

Feature Experiment Ref Rule

description
required
string <= 10000 characters
condition
string
id
required
string
enabled
required
boolean
Array of objects (ScheduleRule)

Simple time-based on/off schedule for this rule

scheduleType
string
Enum: "none" "schedule" "ramp"

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
rampScheduleId
string

ID of the active RampSchedule document controlling this rule. Present when scheduleType is ramp and a live schedule exists.

Array of objects
Array of objects
allProjects
boolean

When true (the default) the rule applies to every project the feature is delivered to. When false the rule is limited to projects.

projects
Array of strings

Project IDs this rule is scoped to when allProjects is false. An empty array scopes the rule to no project.

type
required
string
Value: "experiment-ref"
required
Array of objects
experimentId
required
string
sparse
boolean

JSON features only. When true, each variation value is a partial object merged onto the feature's default value instead of replacing it.

{
  • "description": "string",
  • "condition": "string",
  • "id": "string",
  • "enabled": true,
  • "scheduleRules": [
    ],
  • "scheduleType": "none",
  • "rampScheduleId": "string",
  • "savedGroupTargeting": [
    ],
  • "prerequisites": [
    ],
  • "allProjects": true,
  • "projects": [
    ],
  • "type": "experiment-ref",
  • "variations": [
    ],
  • "experimentId": "string",
  • "sparse": true
}

Feature Experiment Rule

description
required
string <= 10000 characters
condition
string
id
required
string
enabled
required
boolean
Array of objects (ScheduleRule)

Simple time-based on/off schedule for this rule

scheduleType
string
Enum: "none" "schedule" "ramp"

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
rampScheduleId
string

ID of the active RampSchedule document controlling this rule. Present when scheduleType is ramp and a live schedule exists.

Array of objects
Array of objects
allProjects
boolean

When true (the default) the rule applies to every project the feature is delivered to. When false the rule is limited to projects.

projects
Array of strings

Project IDs this rule is scoped to when allProjects is false. An empty array scopes the rule to no project.

type
required
string
Value: "experiment"
trackingKey
string
hashAttribute
string
fallbackAttribute
string
disableStickyBucketing
boolean
bucketVersion
number
minBucketVersion
number
object
coverage
number [ 0 .. 1 ]
Array of objects

Variation values with weights

{
  • "description": "string",
  • "condition": "string",
  • "id": "string",
  • "enabled": true,
  • "scheduleRules": [
    ],
  • "scheduleType": "none",
  • "rampScheduleId": "string",
  • "savedGroupTargeting": [
    ],
  • "prerequisites": [
    ],
  • "allProjects": true,
  • "projects": [
    ],
  • "type": "experiment",
  • "trackingKey": "string",
  • "hashAttribute": "string",
  • "fallbackAttribute": "string",
  • "disableStickyBucketing": true,
  • "bucketVersion": 0,
  • "minBucketVersion": 0,
  • "namespace": {
    },
  • "coverage": 1,
  • "value": [
    ]
}

Feature Force Rule

description
required
string <= 10000 characters
condition
string
id
required
string
enabled
required
boolean
Array of objects (ScheduleRule)

Simple time-based on/off schedule for this rule

scheduleType
string
Enum: "none" "schedule" "ramp"

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
rampScheduleId
string

ID of the active RampSchedule document controlling this rule. Present when scheduleType is ramp and a live schedule exists.

Array of objects
Array of objects
allProjects
boolean

When true (the default) the rule applies to every project the feature is delivered to. When false the rule is limited to projects.

projects
Array of strings

Project IDs this rule is scoped to when allProjects is false. An empty array scopes the rule to no project.

type
required
string
Value: "force"
value
required
string
sparse
boolean

JSON features only. When true, value is a partial object merged onto the feature's default value instead of replacing it.

{
  • "description": "string",
  • "condition": "string",
  • "id": "string",
  • "enabled": true,
  • "scheduleRules": [
    ],
  • "scheduleType": "none",
  • "rampScheduleId": "string",
  • "savedGroupTargeting": [
    ],
  • "prerequisites": [
    ],
  • "allProjects": true,
  • "projects": [
    ],
  • "type": "force",
  • "value": "string",
  • "sparse": true
}

Feature Revision Ref

entityType
required
string
Value: "feature"
id
required
string

Feature Flag id.

version
required
integer

Revision version to publish.

{
  • "entityType": "feature",
  • "id": "string",
  • "version": 0
}

Feature Revision Summary

id
string

Stable id of the feature's live revision.

version
required
integer
comment
required
string
date
required
string <date-time>
object (EventUser)

The user (or automated actor) responsible for an action

object (EventUser)

The user (or automated actor) responsible for an action

{
  • "id": "string",
  • "version": 0,
  • "comment": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "createdBy": {
    },
  • "publishedBy": {
    }
}

Feature Revision V1

id
required
string

Stable revision id. Newer revisions carry opaque ids; older ones a derived frev_<version>_<featureId> form. Both work wherever revision ids are accepted.

featureId
required
string

The feature this revision belongs to

baseVersion
required
integer
version
required
integer
comment
required
string
date
required
string <date-time>
status
required
string
createdBy
string
publishedBy
string
defaultValue
string

The default value at the time this revision was created

required
object
object
object

Per-environment enabled state captured in this revision (only present when kill-switch gating is enabled)

object

Per-environment prerequisites captured in this revision (only present when prerequisite gating is enabled)

Array of objects

Feature-level prerequisites captured in this revision (only present when prerequisite gating is enabled)

object

Metadata fields captured in this revision (only present when metadata gating is enabled)

Array of objects or objects or objects

Pending ramp schedule actions that will be applied when this draft is published

{
  • "id": "string",
  • "featureId": "string",
  • "baseVersion": 0,
  • "version": 0,
  • "comment": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "createdBy": "string",
  • "publishedBy": "string",
  • "defaultValue": "string",
  • "rules": {
    },
  • "definitions": {
    },
  • "environmentsEnabled": {
    },
  • "envPrerequisites": {
    },
  • "prerequisites": [
    ],
  • "metadata": {
    },
  • "rampActions": [
    ]
}

Feature Revision V2

id
required
string

Stable revision id. Newer revisions carry opaque ids; older ones a derived frev_<version>_<featureId> form. Both work wherever revision ids are accepted.

featureId
required
string

The feature this revision belongs to

baseVersion
required
integer
version
required
integer
comment
required
string
date
required
string <date-time>
status
required
string
object (EventUser)

The user (or automated actor) responsible for an action

object (EventUser)

The user (or automated actor) responsible for an action

defaultValue
string

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.

string or null

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.

required
Array of FeatureForceRule (object) or FeatureRolloutRule (object) or FeatureExperimentRule (object) or FeatureRuleV2 (object) or FeatureRuleV2 (object) or FeatureSafeRolloutRule (object) (FeatureRuleV2)

Unified rules array. Each rule carries its own environment scope via allEnvironments / environments.

object
object

Per-environment enabled state captured in this revision (only present when kill-switch gating is enabled)

object

Per-environment prerequisites captured in this revision (only present when prerequisite gating is enabled)

Array of objects

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.

object

Metadata fields captured in this revision (only present when metadata gating is enabled)

Array of objects or objects or objects

Pending ramp schedule actions that will be applied when this draft is published

autoPublishOnApproval
boolean

When true, the revision is armed to publish automatically once governance allows (immediately on approval, or on scheduledPublishAt if set).

string or null

Target date for a deferred (scheduled) publish. Null/absent means publish as soon as approved.

scheduledPublishLockEdits
boolean

When true, content edits to this draft are frozen while the schedule is pending (rebasing is still allowed).

scheduledPublishLockOthers
boolean

When true, publishing other drafts of this feature is blocked while the schedule is pending.

scheduledPublishBypassApproval
boolean

When true, this schedule was armed by an admin via the bypass-approval override. It cannot be edited inline (only canceled and re-armed) and anyone with publish authority may cancel it.

scheduledPublishLastError
string

Set when a due scheduled publish keeps failing (e.g. still awaiting approval, merge conflict). Indicates the schedule is stuck and retrying.

Array of objects

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.

{
  • "id": "string",
  • "featureId": "string",
  • "baseVersion": 0,
  • "version": 0,
  • "comment": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "createdBy": {
    },
  • "publishedBy": {
    },
  • "defaultValue": "string",
  • "defaultValueConfig": "string",
  • "rules": [
    ],
  • "definitions": {
    },
  • "environmentsEnabled": {
    },
  • "envPrerequisites": {
    },
  • "prerequisites": [
    ],
  • "metadata": {
    },
  • "rampActions": [
    ],
  • "autoPublishOnApproval": true,
  • "scheduledPublishAt": "2019-08-24T14:15:22Z",
  • "scheduledPublishLockEdits": true,
  • "scheduledPublishLockOthers": true,
  • "scheduledPublishBypassApproval": true,
  • "scheduledPublishLastError": "string",
  • "reviews": [
    ]
}

Feature Rollout Rule

description
required
string <= 10000 characters
condition
string
id
required
string
enabled
required
boolean
Array of objects (ScheduleRule)

Simple time-based on/off schedule for this rule

scheduleType
string
Enum: "none" "schedule" "ramp"

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
rampScheduleId
string

ID of the active RampSchedule document controlling this rule. Present when scheduleType is ramp and a live schedule exists.

Array of objects
Array of objects
allProjects
boolean

When true (the default) the rule applies to every project the feature is delivered to. When false the rule is limited to projects.

projects
Array of strings

Project IDs this rule is scoped to when allProjects is false. An empty array scopes the rule to no project.

type
required
string
Value: "rollout"
value
required
string
sparse
boolean

JSON features only. When true, value is a partial object merged onto the feature's default value instead of replacing it.

coverage
required
number [ 0 .. 1 ]
hashAttribute
required
string
seed
string

Optional seed for the hash function; defaults to the rule id

1 (number) or 2 (number)

Hash algorithm version for bucketing. Defaults to 2 (preferred) when not specified.

{
  • "description": "string",
  • "condition": "string",
  • "id": "string",
  • "enabled": true,
  • "scheduleRules": [
    ],
  • "scheduleType": "none",
  • "rampScheduleId": "string",
  • "savedGroupTargeting": [
    ],
  • "prerequisites": [
    ],
  • "allProjects": true,
  • "projects": [
    ],
  • "type": "rollout",
  • "value": "string",
  • "sparse": true,
  • "coverage": 1,
  • "hashAttribute": "string",
  • "seed": "string",
  • "hashVersion": 1
}

Feature Rule V1

Any of
description
required
string <= 10000 characters
condition
string
id
required
string
enabled
required
boolean
Array of objects (ScheduleRule)

Simple time-based on/off schedule for this rule

scheduleType
string
Enum: "none" "schedule" "ramp"

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
rampScheduleId
string

ID of the active RampSchedule document controlling this rule. Present when scheduleType is ramp and a live schedule exists.

Array of objects
Array of objects
allProjects
boolean

When true (the default) the rule applies to every project the feature is delivered to. When false the rule is limited to projects.

projects
Array of strings

Project IDs this rule is scoped to when allProjects is false. An empty array scopes the rule to no project.

type
required
string
Value: "force"
value
required
string
sparse
boolean

JSON features only. When true, value is a partial object merged onto the feature's default value instead of replacing it.

Example
{
  • "description": "string",
  • "condition": "string",
  • "id": "string",
  • "enabled": true,
  • "scheduleRules": [
    ],
  • "scheduleType": "none",
  • "rampScheduleId": "string",
  • "savedGroupTargeting": [
    ],
  • "prerequisites": [
    ],
  • "allProjects": true,
  • "projects": [
    ],
  • "type": "force",
  • "value": "string",
  • "sparse": true
}

Feature Rule V2

Any of
description
required
string <= 10000 characters
condition
string
id
required
string
enabled
required
boolean
Array of objects (ScheduleRule)

Simple time-based on/off schedule for this rule

scheduleType
string
Enum: "none" "schedule" "ramp"

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
rampScheduleId
string

ID of the active RampSchedule document controlling this rule. Present when scheduleType is ramp and a live schedule exists.

Array of objects
Array of objects
allProjects
boolean

When true (the default) the rule applies to every project the feature is delivered to. When false the rule is limited to projects.

projects
Array of strings

Project IDs this rule is scoped to when allProjects is false. An empty array scopes the rule to no project.

type
required
string
Value: "force"
value
required
string
sparse
boolean

JSON features only. When true, value is a partial object merged onto the feature's default value instead of replacing it.

string or null

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.

allEnvironments
required
boolean

When true the rule applies to all environments. When false only the environments listed in environments receive the rule.

environments
Array of strings

The environment IDs this rule is active in. Populated when allEnvironments is false.

pendingRamp
string
Enum: "create" "detach"

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.

Example
{
  • "description": "string",
  • "condition": "string",
  • "id": "string",
  • "enabled": true,
  • "scheduleRules": [
    ],
  • "scheduleType": "none",
  • "rampScheduleId": "string",
  • "savedGroupTargeting": [
    ],
  • "prerequisites": [
    ],
  • "allProjects": true,
  • "projects": [
    ],
  • "type": "force",
  • "value": "string",
  • "sparse": true,
  • "config": "string",
  • "allEnvironments": true,
  • "environments": [
    ],
  • "pendingRamp": "create"
}

Feature Safe Rollout Rule

description
required
string <= 10000 characters
condition
string
id
required
string
enabled
required
boolean
Array of objects (ScheduleRule)

Simple time-based on/off schedule for this rule

scheduleType
string
Enum: "none" "schedule" "ramp"

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
rampScheduleId
string

ID of the active RampSchedule document controlling this rule. Present when scheduleType is ramp and a live schedule exists.

Array of objects
Array of objects
allProjects
boolean

When true (the default) the rule applies to every project the feature is delivered to. When false the rule is limited to projects.

projects
Array of strings

Project IDs this rule is scoped to when allProjects is false. An empty array scopes the rule to no project.

type
required
string
Value: "safe-rollout"
controlValue
required
string
variationValue
required
string
seed
string
hashAttribute
string
trackingKey
string
safeRolloutId
string
status
string
Enum: "running" "released" "rolled-back" "stopped"
{
  • "description": "string",
  • "condition": "string",
  • "id": "string",
  • "enabled": true,
  • "scheduleRules": [
    ],
  • "scheduleType": "none",
  • "rampScheduleId": "string",
  • "savedGroupTargeting": [
    ],
  • "prerequisites": [
    ],
  • "allProjects": true,
  • "projects": [
    ],
  • "type": "safe-rollout",
  • "controlValue": "string",
  • "variationValue": "string",
  • "seed": "string",
  • "hashAttribute": "string",
  • "trackingKey": "string",
  • "safeRolloutId": "string",
  • "status": "running"
}

Feature V1

id
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
archived
required
boolean
description
required
string <= 10000 characters
owner
required
string

The userId of the owner (or raw owner name/email for legacy records)

ownerEmail
string

The email address of the owner, when the owner can be resolved to a known user.

project
required
string
targetingAllProjects
boolean
targetingProjects
Array of strings
valueType
required
string
Enum: "boolean" "string" "number" "json"
defaultValue
required
string
string or null

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.)

string or null

Config within baseConfig's family that the default value resolves to (a descendant), or null when the default uses baseConfig directly.

tags
required
Array of strings
required
object
prerequisites
Array of strings

Feature IDs. Each feature must evaluate to true

required
object
object
object or null
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "archived": true,
  • "description": "string",
  • "owner": "string",
  • "ownerEmail": "string",
  • "project": "string",
  • "targetingAllProjects": true,
  • "targetingProjects": [
    ],
  • "valueType": "boolean",
  • "defaultValue": "string",
  • "baseConfig": "string",
  • "defaultValueConfig": "string",
  • "tags": [
    ],
  • "environments": {
    },
  • "prerequisites": [
    ],
  • "revision": {
    },
  • "customFields": {
    },
  • "holdout": {
    }
}

Feature V2

id
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
archived
required
boolean
description
required
string <= 10000 characters
owner
required
string

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.

project
required
string
targetingAllProjects
boolean
targetingProjects
Array of strings
valueType
required
string
Enum: "boolean" "string" "number" "json"
defaultValue
required
string
string or null

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.

string or null

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.

tags
required
Array of strings
required
Array of FeatureForceRule (object) or FeatureRolloutRule (object) or FeatureExperimentRule (object) or FeatureRuleV2 (object) or FeatureRuleV2 (object) or FeatureSafeRolloutRule (object) (FeatureRuleV2)

Unified rules array. Each rule carries its own environment scope via allEnvironments / environments.

required
object

Per-environment enabled state and SDK payload. Rules are on the top-level rules field.

prerequisites
Array of strings

Feature IDs. Each feature must evaluate to true

required
object (FeatureRevisionSummary)
object
object or null
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "archived": true,
  • "description": "string",
  • "owner": "string",
  • "project": "string",
  • "targetingAllProjects": true,
  • "targetingProjects": [
    ],
  • "valueType": "boolean",
  • "defaultValue": "string",
  • "baseConfig": "string",
  • "defaultValueConfig": "string",
  • "tags": [
    ],
  • "rules": [
    ],
  • "environments": {
    },
  • "prerequisites": [
    ],
  • "revision": {
    },
  • "customFields": {
    },
  • "holdout": {
    }
}

Feature With Revisions V1

id
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
archived
required
boolean
description
required
string <= 10000 characters
owner
required
string

The userId of the owner (or raw owner name/email for legacy records)

ownerEmail
string

The email address of the owner, when the owner can be resolved to a known user.

project
required
string
targetingAllProjects
boolean
targetingProjects
Array of strings
valueType
required
string
Enum: "boolean" "string" "number" "json"
defaultValue
required
string
string or null

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.)

string or null

Config within baseConfig's family that the default value resolves to (a descendant), or null when the default uses baseConfig directly.

tags
required
Array of strings
required
object
prerequisites
Array of strings

Feature IDs. Each feature must evaluate to true

required
object
object
object or null
Array of objects (FeatureRevisionV1)
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "archived": true,
  • "description": "string",
  • "owner": "string",
  • "ownerEmail": "string",
  • "project": "string",
  • "targetingAllProjects": true,
  • "targetingProjects": [
    ],
  • "valueType": "boolean",
  • "defaultValue": "string",
  • "baseConfig": "string",
  • "defaultValueConfig": "string",
  • "tags": [
    ],
  • "environments": {
    },
  • "prerequisites": [
    ],
  • "revision": {
    },
  • "customFields": {
    },
  • "holdout": {
    },
  • "revisions": [
    ]
}

Feature With Revisions V2

id
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
archived
required
boolean
description
required
string <= 10000 characters
owner
required
string

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.

project
required
string
targetingAllProjects
boolean
targetingProjects
Array of strings
valueType
required
string
Enum: "boolean" "string" "number" "json"
defaultValue
required
string
string or null

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.

string or null

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.

tags
required
Array of strings
required
Array of FeatureForceRule (object) or FeatureRolloutRule (object) or FeatureExperimentRule (object) or FeatureRuleV2 (object) or FeatureRuleV2 (object) or FeatureSafeRolloutRule (object) (FeatureRuleV2)

Unified rules array. Each rule carries its own environment scope via allEnvironments / environments.

required
object

Per-environment enabled state and SDK payload. Rules are on the top-level rules field.

prerequisites
Array of strings

Feature IDs. Each feature must evaluate to true

required
object (FeatureRevisionSummary)
object
object or null
Array of objects (FeatureRevisionV2)
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "archived": true,
  • "description": "string",
  • "owner": "string",
  • "project": "string",
  • "targetingAllProjects": true,
  • "targetingProjects": [
    ],
  • "valueType": "boolean",
  • "defaultValue": "string",
  • "baseConfig": "string",
  • "defaultValueConfig": "string",
  • "tags": [
    ],
  • "rules": [
    ],
  • "environments": {
    },
  • "prerequisites": [
    ],
  • "revision": {
    },
  • "customFields": {
    },
  • "holdout": {
    },
  • "revisions": [
    ]
}

Information Schema

id
required
string
datasourceId
required
string
status
required
string
Enum: "PENDING" "COMPLETE"
object
required
Array of objects
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
{
  • "id": "string",
  • "datasourceId": "string",
  • "status": "PENDING",
  • "error": {
    },
  • "databases": [
    ],
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z"
}

Information Schema Table

id
required
string
datasourceId
required
string
informationSchemaId
required
string
tableName
required
string
tableSchema
required
string
databaseName
required
string
required
Array of objects
refreshMS
required
number
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
{
  • "id": "string",
  • "datasourceId": "string",
  • "informationSchemaId": "string",
  • "tableName": "string",
  • "tableSchema": "string",
  • "databaseName": "string",
  • "columns": [
    ],
  • "refreshMS": 0,
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z"
}

Lookback Override

type
required
string
Enum: "date" "window"
required
number or string

For "window" type - non-negative numeric value (e.g. 7 for 7 days). For "date" type a date string.

valueUnit
string
Enum: "minutes" "hours" "days" "weeks"

Used when type is "window". Defaults to "days".

{
  • "type": "date",
  • "value": 0,
  • "valueUnit": "minutes"
}

Member

id
required
string
name
string
email
required
string
globalRole
required
string
environments
Array of strings
limitAccessByEnvironment
boolean
managedbyIdp
boolean
teams
Array of strings
Array of objects
lastLoginDate
string <date-time>
dateCreated
string <date-time>
dateUpdated
string <date-time>
{
  • "id": "string",
  • "name": "string",
  • "email": "string",
  • "globalRole": "string",
  • "environments": [
    ],
  • "limitAccessByEnvironment": true,
  • "managedbyIdp": true,
  • "teams": [
    ],
  • "projectRoles": [
    ],
  • "lastLoginDate": "2019-08-24T14:15:22Z",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z"
}

Metric

id
required
string
managedBy
required
string
Enum: "" "api" "config" "admin"

Where this metric must be managed from. If not set (empty string), it can be managed from anywhere.

dateCreated
required
string
dateUpdated
required
string
owner
required
string

The userId of the owner (or raw owner name/email for legacy records)

ownerEmail
string

The email address of the owner, when the owner can be resolved to a known user.

datasourceId
required
string
name
required
string
description
required
string <= 10000 characters
type
required
string
Enum: "binomial" "count" "duration" "revenue"
tags
required
Array of strings
projects
required
Array of strings
archived
required
boolean
required
object
object
object
object
{
  • "id": "string",
  • "managedBy": "",
  • "dateCreated": "string",
  • "dateUpdated": "string",
  • "owner": "string",
  • "ownerEmail": "string",
  • "datasourceId": "string",
  • "name": "string",
  • "description": "string",
  • "type": "binomial",
  • "tags": [
    ],
  • "projects": [
    ],
  • "archived": true,
  • "behavior": {
    },
  • "sql": {
    },
  • "sqlBuilder": {
    },
  • "mixpanel": {
    }
}

Metric Analysis

id
required
string

The ID of the created metric analysis

status
required
string

The status of the analysis (e.g., "running", "completed", "error")

object
{
  • "id": "string",
  • "status": "string",
  • "settings": {
    }
}

Metric Group

id
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
owner
required
string

The userId of the owner (or raw owner name/email for legacy records)

ownerEmail
string

The email address of the owner, when the owner can be resolved to a known user.

name
required
string
description
required
string <= 10000 characters
tags
required
Array of strings
projects
required
Array of strings
metrics
required
Array of strings
datasource
required
string
archived
required
boolean
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "owner": "string",
  • "ownerEmail": "string",
  • "name": "string",
  • "description": "string",
  • "tags": [
    ],
  • "projects": [
    ],
  • "metrics": [
    ],
  • "datasource": "string",
  • "archived": true
}

Metric Usage

metricId
required
string

The metric ID

error
string

Set when the metric does not exist or the caller has no permission to read it.

Array of objects

List of experiments using this metric

string or null

The most recent snapshot attempt across all experiments using this metric

{
  • "metricId": "string",
  • "error": "string",
  • "experiments": [
    ],
  • "lastSnapshotAttempt": "2019-08-24T14:15:22Z"
}

Namespace

id
required
string

The unique internal identifier for the namespace (e.g. 'ns-abc123').

displayName
required
string

Human-readable display name.

description
required
string
status
required
string
Enum: "active" "inactive"
format
required
string
Enum: "legacy" "multiRange"

Namespace format. 'multiRange' supports multiple ranges per experiment and a configurable hash attribute.

hashAttribute
string

The user attribute used to assign bucket membership. Only present on multiRange namespaces.

seed
string

The seed used for bucket hashing. Changing this re-randomizes which traffic is eligible for which experiment. Use the rotateSeed endpoint to change it.

{
  • "id": "string",
  • "displayName": "string",
  • "description": "string",
  • "status": "active",
  • "format": "legacy",
  • "hashAttribute": "string",
  • "seed": "string"
}

Namespace Experiment Member

id
required
string

The internal experiment ID.

name
required
string

Display name of the experiment.

trackingKey
required
string

The experiment tracking key used by the SDK.

status
required
string
Enum: "draft" "running" "stopped"

The current status of the experiment.

required
Array of items

The ranges claimed within this namespace, as [start, end] pairs between 0 and 1.

{
  • "id": "string",
  • "name": "string",
  • "trackingKey": "string",
  • "status": "draft",
  • "ranges": [
    ]
}

Organization

id
string

The Growthbook unique identifier for the organization

externalId
string

An optional identifier that you use within your company for the organization

dateCreated
string <date-time>

The date the organization was created

name
string

The name of the organization

ownerEmail
string

The email address of the organization owner

{
  • "id": "string",
  • "externalId": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "ownerEmail": "string"
}

Pagination Fields

limit
required
integer
offset
required
integer
count
required
integer
total
required
integer
hasMore
required
boolean
required
integer or null
{
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Project

id
required
string
name
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
description
string <= 10000 characters
publicId
string

URL-safe slug used in SDK payload metadata. Auto-generated from name if not provided.

object
{
  • "id": "string",
  • "name": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "publicId": "string",
  • "settings": {
    }
}

Query

id
required
string
organization
required
string
datasource
required
string
language
required
string
query
required
string
queryType
required
string
createdAt
required
string
startedAt
required
string
status
required
string
Enum: "running" "queued" "failed" "partially-succeeded" "succeeded"
externalId
required
string
dependencies
required
Array of strings
runAtEnd
required
boolean
{
  • "id": "string",
  • "organization": "string",
  • "datasource": "string",
  • "language": "string",
  • "query": "string",
  • "queryType": "string",
  • "createdAt": "string",
  • "startedAt": "string",
  • "status": "running",
  • "externalId": "string",
  • "dependencies": [
    ],
  • "runAtEnd": true
}

Ramp Schedule

id
required
string

Unique identifier (rs_ prefix)

dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
name
required
string
entityType
required
string
Value: "feature"
entityId
required
string
required
Array of objects

Controlled entity references

Array of objects

Actions that restore controlled rules to their pre-ramp state. Applied when rolling back or jumping to start.

required
Array of objects

Ordered ramp steps

Array of objects

Actions applied on top of all step patches when the ramp completes. Represents the final desired rule state.

string or null

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.

string or null

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.

requiresStartApproval
boolean

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').

string or null

When the current launch's start was approved. Cleared on every return to step -1 (publish, rollback), re-arming the approval gate.

status
required
string
Enum: "pending" "ready" "running" "paused" "completed" "rolled-back"
currentStepIndex
required
integer >= -1

Index of current step; -1 = not yet started

string or null
string or null

Anchor for cumulative interval timing; resets after each approval gate is satisfied

string or null
required
string or null

When the current step's time gate elapses; null for steps with no interval (pure approval gates) and terminal states

string or null
integer or null

Milliseconds since startedAt (computed at response time, not stored)

object
object or null
experimentHealthAction
string
Enum: "rollback" "hold" "warn"
string or null
object or null

Approval record for the current step. Valid only while stepApproval.stepIndex === currentStepIndex.

awaitingApproval
required
boolean

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.

string or null

When the monitored section most recently started (first monitored step entered). Used for no-traffic grace period gating.

string or null
string or null
object or null

Read-only monitoring status. Present when monitoringConfig is set.

{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "entityType": "feature",
  • "entityId": "string",
  • "targets": [
    ],
  • "startActions": [
    ],
  • "steps": [
    ],
  • "endActions": [
    ],
  • "startDate": "2019-08-24T14:15:22Z",
  • "cutoffDate": "2019-08-24T14:15:22Z",
  • "requiresStartApproval": true,
  • "startApprovedAt": "2019-08-24T14:15:22Z",
  • "status": "pending",
  • "currentStepIndex": -1,
  • "startedAt": "2019-08-24T14:15:22Z",
  • "phaseStartedAt": "2019-08-24T14:15:22Z",
  • "pausedAt": "2019-08-24T14:15:22Z",
  • "nextStepAt": "2019-08-24T14:15:22Z",
  • "nextProcessAt": "2019-08-24T14:15:22Z",
  • "elapsedMs": 0,
  • "lockdownConfig": {
    },
  • "monitoringConfig": {
    },
  • "experimentHealthAction": "rollback",
  • "currentStepEnteredAt": "2019-08-24T14:15:22Z",
  • "stepApproval": {
    },
  • "awaitingApproval": true,
  • "monitoringStartDate": "2019-08-24T14:15:22Z",
  • "lastRollbackAt": "2019-08-24T14:15:22Z",
  • "lastRollbackReason": "string",
  • "monitoringStatus": {
    }
}

Ramp Schedule Template

id
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
name
required
string
required
Array of objects
object
official
boolean
object or null
object or null
order
required
number

Manual display order within the org (read-only; managed via the app).

{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "steps": [
    ],
  • "endPatch": {
    },
  • "official": true,
  • "monitoringConfig": {
    },
  • "lockdownConfig": {
    },
  • "order": 0
}

Report

id
required
string
dateCreated
required
string
dateUpdated
required
string
title
required
string
description
required
string
type
required
string
Enum: "experiment-snapshot" "experiment"

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.

status
string
Enum: "published" "private"

UI lifecycle marker. Note: this does NOT control public shareability — see shareLevel for visibility controls.

shareLevel
string
Enum: "public" "organization" "private"

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.

shareUrl
string

Public URL for viewing the report. Only present when shareLevel is public.

experimentId
string
snapshotId
string

Snapshot ID (experiment-snapshot type only)

snapshotStatus
string
Enum: "running" "success" "error"

Status of the latest snapshot (poll this after refresh)

snapshotError
string

Error message if snapshot failed

object
object
object (ExperimentResults)
{
  • "id": "string",
  • "dateCreated": "string",
  • "dateUpdated": "string",
  • "title": "string",
  • "description": "string",
  • "type": "experiment-snapshot",
  • "status": "published",
  • "shareLevel": "public",
  • "shareUrl": "string",
  • "experimentId": "string",
  • "snapshotId": "string",
  • "snapshotStatus": "running",
  • "snapshotError": "string",
  • "analysisSettings": {
    },
  • "experimentMetadata": {
    },
  • "results": {
    }
}

Revision Id Ref

entityType
required
string
Enum: "feature" "saved-group" "config" "constant"
revisionId
required
string

A revision id from this API or the revision webhooks (rev_… / frev_…). Alternative to identifier + version.

{
  • "entityType": "feature",
  • "revisionId": "string"
}

Safe Rollout Rule

description
string
enabled
boolean
condition
string
Array of objects
Array of objects
allEnvironments
boolean

When true the rule applies to all environments. Defaults to false.

environments
Array of strings

Specific environment IDs this rule applies to. Used when allEnvironments is false.

type
required
string

Must be "safe-rollout" for a safe rollout rule.

Value: "safe-rollout"
controlValue
required
string
variationValue
required
string
hashAttribute
required
string
trackingKey
string
seed
string
required
object
{
  • "description": "string",
  • "enabled": true,
  • "condition": "string",
  • "savedGroups": [
    ],
  • "prerequisites": [
    ],
  • "allEnvironments": true,
  • "environments": [
    ],
  • "type": "safe-rollout",
  • "controlValue": "string",
  • "variationValue": "string",
  • "hashAttribute": "string",
  • "trackingKey": "string",
  • "seed": "string",
  • "safeRolloutFields": {
    }
}

Saved Group

id
required
string
type
required
string
Enum: "condition" "list"
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
name
required
string
owner
string

The userId of the owner (or raw owner name/email for legacy records)

ownerEmail
string

The email address of the owner, when the owner can be resolved to a known user.

condition
string

When type = 'condition', this is the JSON-encoded condition for the group

attributeKey
string

When type = 'list', this is the attribute key the group is based on

values
Array of strings

When type = 'list', this is the list of values for the attribute key

description
string <= 10000 characters
projects
Array of strings
archived
boolean
useEmptyListGroup
boolean
{
  • "id": "string",
  • "type": "condition",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "owner": "string",
  • "ownerEmail": "string",
  • "condition": "string",
  • "attributeKey": "string",
  • "values": [
    ],
  • "description": "string",
  • "projects": [
    ],
  • "archived": true,
  • "useEmptyListGroup": true
}

Saved Group References

required
Array of objects
required
Array of objects
required
Array of objects
{
  • "features": [
    ],
  • "experiments": [
    ],
  • "savedGroups": [
    ]
}

Saved Group Revision

id
required
string
version
integer
title
string
status
required
string
Enum: "draft" "pending-review" "approved" "changes-requested" "merged" "discarded"
authorId
required
string
authorEmail
string
contributors
Array of strings
revertedFrom
string
required
Array of objects (SavedGroupRevisionReview)
required
Array of objects (SavedGroupRevisionActivityLogEntry)
object
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
required
object (SavedGroup)
required
object (SavedGroup)
required
Array of objects or objects or objects or objects or objects or objects
{
  • "id": "string",
  • "version": 0,
  • "title": "string",
  • "status": "draft",
  • "authorId": "string",
  • "authorEmail": "string",
  • "contributors": [
    ],
  • "revertedFrom": "string",
  • "reviews": [
    ],
  • "activityLog": [
    ],
  • "resolution": {
    },
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "baseSavedGroup": {
    },
  • "proposedSavedGroup": {
    },
  • "proposedChanges": [
    ]
}

Saved Group Revision Activity Log Entry

id
required
string
userId
required
string
action
required
string
Enum: "created" "updated" "reviewed" "approved" "requested-changes" "commented" "review-requested" "review-retracted" "merged" "discarded" "reopened" "scheduled-publish" "scheduled-publish-updated" "scheduled-publish-canceled"
string or null
Array of objects or objects or objects or objects or objects or objects
targetSnapshot
any
dateCreated
required
string <date-time>
{
  • "id": "string",
  • "userId": "string",
  • "action": "created",
  • "description": "string",
  • "proposedChangesSnapshot": [
    ],
  • "targetSnapshot": null,
  • "dateCreated": "2019-08-24T14:15:22Z"
}

Saved Group Revision Ref

entityType
required
string
Value: "saved-group"
id
required
string

Saved Group id.

version
required
integer

Revision version to publish.

{
  • "entityType": "saved-group",
  • "id": "string",
  • "version": 0
}

Saved Group Revision Review

id
required
string
userId
required
string
decision
required
string
Enum: "approve" "request-changes" "comment"
comment
string
stale
boolean

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.

dateCreated
required
string <date-time>
{
  • "id": "string",
  • "userId": "string",
  • "decision": "approve",
  • "comment": "string",
  • "stale": true,
  • "dateCreated": "2019-08-24T14:15:22Z"
}

Schedule Rule

enabled
required
boolean

Whether the rule should be enabled or disabled at the specified timestamp.

required
string or null

ISO timestamp when the rule should activate.

{
  • "enabled": true,
  • "timestamp": "2019-08-24T14:15:22Z"
}

Sdk Connection

id
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
name
required
string
organization
required
string
languages
required
Array of strings
sdkVersion
string
environment
required
string
project
required
string

Use 'projects' instead. This is only for backwards compatibility and contains the first project only.

projects
Array of strings
encryptPayload
required
boolean
encryptionKey
required
string
includeVisualExperiments
boolean
includeDraftExperiments
boolean
includeDraftExperimentRefs
boolean

When true, experiment-ref rules linked to draft experiments are included in feature definitions. Off by default.

includeExperimentNames
boolean
includeRedirectExperiments
boolean
includeRuleIds
boolean
includeProjectIdInMetadata
boolean
includeCustomFieldsInMetadata
boolean
allowedCustomFieldsInMetadata
Array of strings
includeTagsInMetadata
boolean
key
required
string
proxyEnabled
required
boolean
proxyHost
required
string
proxySigningKey
required
string
sseEnabled
boolean
hashSecureAttributes
boolean
remoteEvalEnabled
boolean
savedGroupReferencesEnabled
boolean
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "organization": "string",
  • "languages": [
    ],
  • "sdkVersion": "string",
  • "environment": "string",
  • "project": "string",
  • "projects": [
    ],
  • "encryptPayload": true,
  • "encryptionKey": "string",
  • "includeVisualExperiments": true,
  • "includeDraftExperiments": true,
  • "includeDraftExperimentRefs": true,
  • "includeExperimentNames": true,
  • "includeRedirectExperiments": true,
  • "includeRuleIds": true,
  • "includeProjectIdInMetadata": true,
  • "includeCustomFieldsInMetadata": true,
  • "allowedCustomFieldsInMetadata": [
    ],
  • "includeTagsInMetadata": true,
  • "key": "string",
  • "proxyEnabled": true,
  • "proxyHost": "string",
  • "proxySigningKey": "string",
  • "sseEnabled": true,
  • "hashSecureAttributes": true,
  • "remoteEvalEnabled": true,
  • "savedGroupReferencesEnabled": true
}

Segment

id
required
string
owner
required
string

The userId of the owner (or raw owner name/email for legacy records)

ownerEmail
string

The email address of the owner, when the owner can be resolved to a known user.

datasourceId
required
string
identifierType
required
string
name
required
string
description
string <= 10000 characters
query
string
dateCreated
required
string
dateUpdated
required
string
managedBy
string
Enum: "" "api" "config"

Where this segment must be managed from. If not set (empty string), it can be managed from anywhere.

type
string
Enum: "SQL" "FACT"
factTableId
string
filters
Array of strings
projects
Array of strings
{
  • "id": "string",
  • "owner": "string",
  • "ownerEmail": "string",
  • "datasourceId": "string",
  • "identifierType": "string",
  • "name": "string",
  • "description": "string",
  • "query": "string",
  • "dateCreated": "string",
  • "dateUpdated": "string",
  • "managedBy": "",
  • "type": "SQL",
  • "factTableId": "string",
  • "filters": [
    ],
  • "projects": [
    ]
}

Settings

confidenceLevel
required
number
required
object or null
required
object
pastExperimentsMinLength
required
number
metricAnalysisDays
required
number
required
object or null
multipleExposureMinPercent
required
number
required
object
statsEngine
required
string
pValueThreshold
required
number
regressionAdjustmentEnabled
required
boolean
regressionAdjustmentDays
required
number
sequentialTestingEnabled
required
boolean
sequentialTestingTuningParameter
required
number
attributionModel
required
string
Enum: "firstExposure" "experimentDuration" "lookbackOverride"
targetMDE
required
number
delayHours
required
number
windowType
required
string
windowHours
required
number
winRisk
required
number
loseRisk
required
number
secureAttributeSalt
required
string
killswitchConfirmation
required
boolean
featureKillSwitchBehavior
string
Enum: "off" "warn"
required
Array of objects
Array of objects
restApiBypassesReviews
boolean
requireRebaseBeforePublish
boolean
revertsBypassApproval
boolean
maxConcurrentDrafts
number
featureKeyExample
required
string
featureRegexValidator
required
string
sparseJSONRulesByDefault
boolean
banditScheduleValue
required
number
banditScheduleUnit
required
string
Enum: "hours" "days"
banditBurnInValue
required
number
banditBurnInUnit
required
string
Enum: "hours" "days"
experimentMinLengthDays
required
number
number or null
string or null
maxMetricSliceLevels
number
topValuesLookbackValue
number
topValuesLookbackUnit
string
Value: "days"
{
  • "confidenceLevel": 0,
  • "northStar": {
    },
  • "metricDefaults": {
    },
  • "pastExperimentsMinLength": 0,
  • "metricAnalysisDays": 0,
  • "updateSchedule": {
    },
  • "multipleExposureMinPercent": 0,
  • "defaultRole": {
    },
  • "statsEngine": "string",
  • "pValueThreshold": 0,
  • "regressionAdjustmentEnabled": true,
  • "regressionAdjustmentDays": 0,
  • "sequentialTestingEnabled": true,
  • "sequentialTestingTuningParameter": 0,
  • "attributionModel": "firstExposure",
  • "targetMDE": 0,
  • "delayHours": 0,
  • "windowType": "string",
  • "windowHours": 0,
  • "winRisk": 0,
  • "loseRisk": 0,
  • "secureAttributeSalt": "string",
  • "killswitchConfirmation": true,
  • "featureKillSwitchBehavior": "off",
  • "requireReviews": [
    ],
  • "targetingReviewMode": [
    ],
  • "restApiBypassesReviews": true,
  • "requireRebaseBeforePublish": true,
  • "revertsBypassApproval": true,
  • "maxConcurrentDrafts": 0,
  • "featureKeyExample": "string",
  • "featureRegexValidator": "string",
  • "sparseJSONRulesByDefault": true,
  • "banditScheduleValue": 0,
  • "banditScheduleUnit": "hours",
  • "banditBurnInValue": 0,
  • "banditBurnInUnit": "hours",
  • "experimentMinLengthDays": 0,
  • "experimentMaxLengthDays": 0,
  • "preferredEnvironment": "string",
  • "maxMetricSliceLevels": 0,
  • "topValuesLookbackValue": 0,
  • "topValuesLookbackUnit": "days"
}

Targeting Rule

description
string
enabled
boolean
condition
string
Array of objects
Array of objects
allEnvironments
boolean

When true the rule applies to all environments. Defaults to false.

environments
Array of strings

Specific environment IDs this rule applies to. Used when allEnvironments is false.

type
string
Enum: "force" "rollout"

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.

value
required
string

The value to serve when this rule matches.

string or null

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.

sparse
boolean

JSON features only. When true, the rule value is a partial object merged onto the feature's default value instead of replacing it.

coverage
number [ 0 .. 1 ]

Percentage of users to include (0–1). Defaults to 1. When less than 1, hashAttribute is required.

hashAttribute
string

Attribute to hash on for consistent assignment. Required when coverage < 1.

seed
string
1 (number) or 2 (number)

Hash algorithm version for bucketing. Defaults to 2 (preferred) when not specified.

{
  • "description": "string",
  • "enabled": true,
  • "condition": "string",
  • "savedGroups": [
    ],
  • "prerequisites": [
    ],
  • "allEnvironments": true,
  • "environments": [
    ],
  • "type": "force",
  • "value": "string",
  • "config": "string",
  • "sparse": true,
  • "coverage": 1,
  • "hashAttribute": "string",
  • "seed": "string",
  • "hashVersion": 1
}

Team

id
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
name
required
string
createdBy
required
string
description
required
string
role
required
string
limitAccessByEnvironment
required
boolean
environments
required
Array of strings
Array of objects
members
required
Array of strings
managedByIdp
required
boolean
object
defaultProject
string
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "createdBy": "string",
  • "description": "string",
  • "role": "string",
  • "limitAccessByEnvironment": true,
  • "environments": [
    ],
  • "projectRoles": [
    ],
  • "members": [
    ],
  • "managedByIdp": true,
  • "managedBy": {
    },
  • "defaultProject": "string"
}

Visual Change

description
string
css
string
js
string
variation
required
string
Array of objects
{
  • "description": "string",
  • "css": "string",
  • "js": "string",
  • "variation": "string",
  • "domMutations": [
    ]
}

Visual Changeset

id
string
required
Array of objects
editorUrl
required
string
experiment
required
string
required
Array of objects
{
  • "id": "string",
  • "urlPatterns": [
    ],
  • "editorUrl": "string",
  • "experiment": "string",
  • "visualChanges": [
    ]
}