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 - Unprocessable Entity - The request is valid, but a warning, validation rule, approval requirement, or another publishing gate blocked it. Do not assume that ignoreWarnings clears every 422 response.
  • 429 - Too Many Requests - You exceeded the rate limit of 60 requests per minute. Try again later.
  • 5XX - Server Error - Something went wrong on GrowthBook's end (these are rare)

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

  • message - Information about the error

Publishing gates

Publish responses include a gates array that explains every blocker:

  • type, severity, and messages identify the problem.
  • override names the request-body field that can bypass it. This is ignoreWarnings for warnings, skipSchemaValidation for schema and invariant failures, or skipHooks for Custom Hook rejections. A value of null means there is no request-body override.
  • requiresPermission identifies any additional permission needed to use the override.
  • resolution provides an API action, method, and path when the blocker must be resolved another way.

For example, an approval gate is cleared by approving the revision or by using a caller with Bypass draft approvals access. A Config lock is cleared through the unlock route in resolution.

When a successful publish bypasses a gate, the response includes bypassedGates. Each entry reports the gate type and how it was bypassed in via, which is one of ignoreWarnings, skipSchemaValidation, skipHooks, bypassApprovalPermission, restApiBypassesReviews, or revertsBypassApproval (reverts only). This field is omitted when no gates were bypassed.

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 Flag. The caller needs Create access in its Project, plus Publish access for any environment the Feature Flag starts enabled in — one that starts disabled everywhere needs Create alone. Rules are supplied as a top-level rules array; each rule includes allEnvironments / environments scope fields.

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 Feature Flag in Config mode. The config must be live. This is the family root and the base the default value patches.
  • Default value: unlike rules, the default is exactly a config with no overrides of its own — send defaultValue: "{}" to use baseConfig. To resolve the default to a descendant of baseConfig instead, set defaultValueConfig to that descendant's key (it must be within baseConfig's family); omit/null to use baseConfig directly.
  • Rules & experiment variations: each carries its own config field naming the family config that value patches (omit/null to patch the base). value is the override patch.

Example:

{
  "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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

skipSchemaValidation
boolean

Set to true to publish despite schema validation errors, failed invariants, or schema changes that invalidate dependent resources. This does not bypass a rejected Custom Hook; use skipHooks for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

skipHooks
boolean

Set to true to publish despite a Custom Hook rejection. This does not bypass schema validation; use skipSchemaValidation for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

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 the Feature Flag and immediately publishes a new revision. The caller needs Edit access in the Feature Flag's Project and Publish access for every affected environment. When approval is required, use the revision endpoints instead, unless the caller can bypass draft approvals.

Other top-level fields are patch-merged: omit a field to leave it unchanged. The rules field, when supplied, replaces the entire rules array in one operation. To preserve existing rules, fetch the Feature Flag, update the returned rules array, and send the complete array back. Safe-rollout rules round-trip through safeRolloutId; use POST /v2/features/:id/revisions/:version/rules to create new ones.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

skipSchemaValidation
boolean

Set to true to publish despite schema validation errors, failed invariants, or schema changes that invalidate dependent resources. This does not bypass a rejected Custom Hook; use skipHooks for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

skipHooks
boolean

Set to true to publish despite a Custom Hook rejection. This does not bypass schema validation; use skipSchemaValidation for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

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": {
    },
  • "bypassedGates": [
    ]
}

Deletes a single feature

Permanently deletes a Feature Flag and all of its revisions. The caller needs Archive & delete access. Deleting a live Feature Flag also requires Publish access for every environment where it is enabled and the organization setting "REST API always bypasses approval requirements". Otherwise, archive the Feature Flag before deleting it.

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 Flag in one or more environments and immediately publishes the change. The caller needs Publish access for every environment in the request. When approval is required, use a draft revision instead, unless the caller can bypass draft approvals.

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": {
    },
  • "bypassedGates": [
    ]
}

Revert a feature to a specific revision

Restores a previously published revision and immediately publishes the result as a new revision. The caller needs Revert access for every affected environment. When approval is required, the request is allowed only if the caller holds the FlagsBypassApprovals policy, or the organization enables either "REST API always bypasses approval requirements" or "Allow reverts without approval".

If the restored values no longer match the Feature Flag's current value type or JSON schema, the API returns 422 with warnings. Send "ignoreWarnings": true to acknowledge those warnings and continue.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

skipSchemaValidation
boolean

Set to true to publish despite schema validation errors, failed invariants, or schema changes that invalidate dependent resources. This does not bypass a rejected Custom Hook; use skipHooks for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

skipHooks
boolean

Set to true to publish despite a Custom Hook rejection. This does not bypass schema validation; use skipSchemaValidation for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

Responses

Request samples

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

Response samples

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

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

skipSchemaValidation
boolean

Set to true to publish despite schema validation errors, failed invariants, or schema changes that invalidate dependent resources. This does not bypass a rejected Custom Hook; use skipHooks for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

skipHooks
boolean

Set to true to publish despite a Custom Hook rejection. This does not bypass schema validation; use skipSchemaValidation for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

skipSchemaValidation
boolean

Set to true to publish despite schema validation errors, failed invariants, or schema changes that invalidate dependent resources. This does not bypass a rejected Custom Hook; use skipHooks for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

skipHooks
boolean

Set to true to publish despite a Custom Hook rejection. This does not bypass schema validation; use skipSchemaValidation for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

skipSchemaValidation
boolean

Set to true to publish despite schema validation errors, failed invariants, or schema changes that invalidate dependent resources. This does not bypass a rejected Custom Hook; use skipHooks for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

skipHooks
boolean

Set to true to publish despite a Custom Hook rejection. This does not bypass schema validation; use skipSchemaValidation for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Schedules the draft to publish on or after scheduledPublishAt. When approval is required, publishing waits until the draft is also approved. Send scheduledPublishAt: null to cancel the schedule.

Set lockEdits to prevent content changes while the schedule is pending; rebasing remains allowed. Set lockOthers to prevent other drafts of this Feature Flag from being published until this schedule runs or is canceled. The caller needs Publish access, and that access is checked again when the schedule runs. A caller with Bypass draft approvals access can schedule an unapproved draft by sending bypassApproval: true. That schedule must be canceled and recreated before it can be changed.

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

When to publish, as an RFC3339 timestamp (e.g. 2026-01-31T09:00:00Z or 2026-01-31T02:00:00-07:00), or null to cancel a pending schedule.

ignoreWarnings
boolean

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

skipSchemaValidation
boolean

Set to true to publish despite schema validation errors, failed invariants, or schema changes that invalidate dependent resources. This does not bypass a rejected Custom Hook; use skipHooks for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

skipHooks
boolean

Set to true to publish despite a Custom Hook rejection. This does not bypass schema validation; use skipSchemaValidation for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

lockEdits
boolean
lockOthers
boolean
bypassApproval
boolean

Responses

Request samples

Content type
application/json
{
  • "scheduledPublishAt": "2019-08-24T14:15:22Z",
  • "ignoreWarnings": true,
  • "skipSchemaValidation": true,
  • "skipHooks": true,
  • "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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Publishes the draft and makes its changes live. The caller needs Publish access for every affected environment. When approval is required, the draft must be approved unless the caller has Bypass draft approvals access. If the organization requires rebasing, an out-of-date draft must be rebased first; an authorized caller can instead send ignoreWarnings: true to force-publish it. Any pending ramp actions in pendingRamp are applied as part of the same operation. A 422 response lists every blocking gate and the available resolution.

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

Deprecated and ignored. Approval is bypassed automatically when the caller has Bypass draft approvals access for this resource or when the organization enables the REST API approval bypass. Otherwise, the revision must be approved before it can be published.

ignoreWarnings
boolean

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

skipSchemaValidation
boolean

Set to true to publish despite schema validation errors, failed invariants, or schema changes that invalidate dependent resources. This does not bypass a rejected Custom Hook; use skipHooks for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

skipHooks
boolean

Set to true to publish despite a Custom Hook rejection. This does not bypass schema validation; use skipSchemaValidation for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

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
ignoreWarnings
boolean

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

skipSchemaValidation
boolean

Set to true to publish despite schema validation errors, failed invariants, or schema changes that invalidate dependent resources. This does not bypass a rejected Custom Hook; use skipHooks for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

skipHooks
boolean

Set to true to publish despite a Custom Hook rejection. This does not bypass schema validation; use skipSchemaValidation for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

Responses

Request samples

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

Response samples

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

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

skipSchemaValidation
boolean

Set to true to publish despite schema validation errors, failed invariants, or schema changes that invalidate dependent resources. This does not bypass a rejected Custom Hook; use skipHooks for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

skipHooks
boolean

Set to true to publish despite a Custom Hook rejection. This does not bypass schema validation; use skipSchemaValidation for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

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 the Feature Flag and immediately publishes a new revision. The caller needs Edit access in the Feature Flag's Project and Publish access for every affected environment. When approval is required, use the revision endpoints instead, unless the caller can bypass draft approvals.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

skipSchemaValidation
boolean

Set to true to publish despite schema validation errors, failed invariants, or schema changes that invalidate dependent resources. This does not bypass a rejected Custom Hook; use skipHooks for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

skipHooks
boolean

Set to true to publish despite a Custom Hook rejection. This does not bypass schema validation; use skipSchemaValidation for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

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": {
    },
  • "bypassedGates": [
    ]
}

Deletes a single feature Deprecated

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

Permanently deletes a Feature Flag and all of its revisions. The caller needs Archive & delete access. Deleting a live Feature Flag also requires Publish access for every environment where it is enabled and the organization setting "REST API always bypasses approval requirements". Otherwise, archive the Feature Flag before deleting it.

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 Flag in one or more environments and immediately publishes the change. The caller needs Publish access for every environment in the request. When approval is required, use a draft revision instead, unless the caller can bypass draft approvals.

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": {
    },
  • "bypassedGates": [
    ]
}

Revert a feature to a specific revision Deprecated

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

Restores a previously published revision and immediately publishes the result as a new revision. The caller needs Revert access for every affected environment. When approval is required, the request is allowed only if the caller holds the FlagsBypassApprovals policy, or the organization enables either "REST API always bypasses approval requirements" or "Allow reverts without approval".

If the restored values no longer match the Feature Flag's current value type or JSON schema, the API returns 422 with warnings. Send "ignoreWarnings": true to acknowledge those warnings and continue.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

skipSchemaValidation
boolean

Set to true to publish despite schema validation errors, failed invariants, or schema changes that invalidate dependent resources. This does not bypass a rejected Custom Hook; use skipHooks for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

skipHooks
boolean

Set to true to publish despite a Custom Hook rejection. This does not bypass schema validation; use skipSchemaValidation for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

Responses

Request samples

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

Response samples

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

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

skipSchemaValidation
boolean

Set to true to publish despite schema validation errors, failed invariants, or schema changes that invalidate dependent resources. This does not bypass a rejected Custom Hook; use skipHooks for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

skipHooks
boolean

Set to true to publish despite a Custom Hook rejection. This does not bypass schema validation; use skipSchemaValidation for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

skipSchemaValidation
boolean

Set to true to publish despite schema validation errors, failed invariants, or schema changes that invalidate dependent resources. This does not bypass a rejected Custom Hook; use skipHooks for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

skipHooks
boolean

Set to true to publish despite a Custom Hook rejection. This does not bypass schema validation; use skipSchemaValidation for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

skipSchemaValidation
boolean

Set to true to publish despite schema validation errors, failed invariants, or schema changes that invalidate dependent resources. This does not bypass a rejected Custom Hook; use skipHooks for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

skipHooks
boolean

Set to true to publish despite a Custom Hook rejection. This does not bypass schema validation; use skipSchemaValidation for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

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.

Publishes the draft and makes its changes live. The caller needs Publish access for every affected environment. When approval is required, the draft must be approved unless the caller has Bypass draft approvals access.

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

Deprecated and ignored. Approval is bypassed automatically when the caller has Bypass draft approvals access for this resource or when the organization enables the REST API approval bypass. Otherwise, the revision must be approved before it can be published.

ignoreWarnings
boolean

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

skipSchemaValidation
boolean

Set to true to publish despite schema validation errors, failed invariants, or schema changes that invalidate dependent resources. This does not bypass a rejected Custom Hook; use skipHooks for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

skipHooks
boolean

Set to true to publish despite a Custom Hook rejection. This does not bypass schema validation; use skipSchemaValidation for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

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
ignoreWarnings
boolean

Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access.

skipSchemaValidation
boolean

Set to true to publish despite schema validation errors, failed invariants, or schema changes that invalidate dependent resources. This does not bypass a rejected Custom Hook; use skipHooks for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

skipHooks
boolean

Set to true to publish despite a Custom Hook rejection. This does not bypass schema validation; use skipSchemaValidation for that. The caller must have Bypass draft approvals access for Feature Flags, Configs, and Constants in every Project. Otherwise, this field is ignored.

Responses

Request samples

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

Response samples

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

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 FlagsBypassApprovals permission and is logged in the audit trail.

Two common uses:

  • Post-interval monitoring hold (decision: "hold", interval elapsed): the step timer has completed but a signal or guardrail is flagging concern. Use this after reviewing the /status health summary and deciding to accept the risk and proceed.
  • Hard override: skip a step regardless of where it is in its interval or hold conditions (CI gate, external deployment pipeline).

When to use other actions instead:

  • /actions/resume — restores a paused schedule without moving the step.
  • /actions/approve-step — clears only the approval gate; other conditions still resolve naturally.
  • /actions/rollback — preferred response when decision: "rollback" or signals include guardrail-failing.
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 (FlagsBypassApprovals) 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. Health-action thresholds (srmAction, noTrafficAction, etc.) can be updated at any time.

Once a linked SafeRollout has started, datasourceId, exposureQueryId, the metric IDs and the snapshot cadence are all locked — stop and recreate the schedule to change the data source.

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

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": {