GrowthBook features-v2 API
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.
OpenAPI Specification
openapi: 3.1.0
info:
version: 1.0.0
title: GrowthBook REST AnalyticsExplorations features-v2 API
description: "GrowthBook offers a full REST API for interacting with the application.\n\nRequest data can use either JSON or Form data encoding (with proper `Content-Type` headers). All response bodies are JSON-encoded.\n\nThe 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.\n\n## Versioning\n\nEndpoints are versioned by path prefix:\n\n- `/v1/...` — stable, widely-supported endpoints\n- `/v2/...` — updated endpoints with improved shapes (e.g. unified per-rule environment scope for feature flags)\n\nNew integrations should prefer v2 where available.\n\n## Authentication\n\nWe support both the HTTP Basic and Bearer authentication schemes for convenience.\n\nYou first need to generate a new API Key in GrowthBook. Different keys have different permissions:\n\n- **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.\n- **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`\n\nIf 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)\n\n```bash\ncurl https://api.growthbook.io/api/v1/features \\\n -u secret_abc123DEF456:\n```\n\nIf using Bearer auth, pass the Secret Key as the token:\n\n```bash\ncurl https://api.growthbook.io/api/v1/features \\\n-H \"Authorization: Bearer secret_abc123DEF456\"\n```\n\n## Errors\n\nThe API may return the following error status codes:\n\n- **400** - Bad Request - Often due to a missing required parameter\n- **401** - Unauthorized - No valid API key provided\n- **402** - Request Failed - The parameters are valid, but the request failed\n- **403** - Forbidden - Provided API key does not have the required access\n- **404** - Not Found - Unknown API route or requested resource\n- **429** - Too Many Requests - You exceeded the rate limit of 60 requests per minute. Try again later.\n- **5XX** - Server Error - Something went wrong on GrowthBook's end (these are rare)\n\nThe response body will be a JSON object with the following properties:\n\n- **message** - Information about the error\n"
servers:
- url: https://api.growthbook.io/api
description: GrowthBook Cloud
- url: https://{domain}/api
description: Self-hosted GrowthBook
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: features-v2
x-displayName: Feature Flags
description: 'Control your feature flags programatically.
Rules are returned as a unified top-level array; each rule carries `allEnvironments` / `environments` scope fields instead of being bucketed by environment.'
paths:
/v2/features:
get:
operationId: listFeaturesV2
summary: Get all features
description: 'Returns features with pagination. Rules are returned as a unified top-level array with per-rule environment scope.
'
tags:
- features-v2
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/projectId'
- $ref: '#/components/parameters/clientKey'
- $ref: '#/components/parameters/skipPagination'
responses:
'200':
content:
application/json:
schema:
allOf:
- type: object
properties:
features:
type: array
items:
$ref: '#/components/schemas/FeatureV2'
required:
- features
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: "curl -X GET 'https://api.growthbook.io/api/v2/features' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
post:
operationId: postFeatureV2
summary: Create a single feature
description: Creates a new feature. Rules are supplied as a top-level `rules` array; each rule includes `allEnvironments` / `environments` scope fields.
tags:
- features-v2
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
description: A unique key name for the feature. Feature keys can only include letters, numbers, hyphens, and underscores.
type: string
minLength: 1
archived:
type: boolean
description:
description: Description of the feature
type: string
owner:
description: The userId or email address of the owner. If an email address is provided, it will be used to look up the userId of the matching organization member. If an ID is provided, it will be validated as existing in the organization.
type: string
project:
description: An associated project ID
type: string
valueType:
description: The data type of the feature payload. Boolean by default.
type: string
enum:
- boolean
- string
- number
- json
defaultValue:
description: Default value when feature is enabled. Type must match `valueType`.
type: string
tags:
description: List of associated tags
type: array
items:
type: string
rules:
description: Feature rules. Each rule carries its own environment scope via `allEnvironments` / `environments`.
type: array
items:
anyOf:
- type: object
properties:
description:
type: string
condition:
type: string
savedGroupTargeting:
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
anyOf:
- type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
id:
type: string
enabled:
type: boolean
type:
type: string
const: force
value:
type: string
allEnvironments:
description: When true the rule applies to all environments (default).
type: boolean
environments:
description: Specific environment IDs this rule applies to. Required when allEnvironments is false.
type: array
items:
type: string
required:
- type
- value
additionalProperties: false
- type: object
properties:
description:
type: string
condition:
type: string
savedGroupTargeting:
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
anyOf:
- type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
id:
type: string
enabled:
type: boolean
type:
type: string
const: rollout
value:
type: string
coverage:
type: number
hashAttribute:
type: string
allEnvironments:
description: When true the rule applies to all environments (default).
type: boolean
environments:
description: Specific environment IDs this rule applies to. Required when allEnvironments is false.
type: array
items:
type: string
required:
- type
- value
- coverage
- hashAttribute
additionalProperties: false
- type: object
properties:
description:
type: string
id:
type: string
enabled:
type: boolean
type:
type: string
const: experiment-ref
condition:
type: string
savedGroupTargeting:
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
anyOf:
- type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
variations:
type: array
items:
type: object
properties:
value:
type: string
variationId:
type: string
required:
- value
- variationId
additionalProperties: false
experimentId:
type: string
allEnvironments:
description: When true the rule applies to all environments (default).
type: boolean
environments:
description: Specific environment IDs this rule applies to. Required when allEnvironments is false.
type: array
items:
type: string
required:
- type
- variations
- experimentId
additionalProperties: false
- type: object
properties:
description:
type: string
id:
type: string
enabled:
type: boolean
type:
type: string
const: safe-rollout
condition:
type: string
savedGroupTargeting:
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
anyOf:
- type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
controlValue:
type: string
variationValue:
type: string
hashAttribute:
type: string
trackingKey:
type: string
seed:
type: string
safeRolloutId:
description: ID of an existing SafeRollout on this feature. Bulk POST/PUT cannot create new safe-rollouts; use POST /v2/features/:id/revisions/:version/rules to create one.
type: string
status:
type: string
enum:
- running
- released
- rolled-back
- stopped
allEnvironments:
description: When true the rule applies to all environments (default).
type: boolean
environments:
description: Specific environment IDs this rule applies to. Required when allEnvironments is false.
type: array
items:
type: string
required:
- type
- controlValue
- variationValue
- hashAttribute
- safeRolloutId
additionalProperties: false
environments:
description: Per-environment enabled state. V2 rules are specified on the top-level `rules` field.
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
enabled:
type: boolean
additionalProperties: false
prerequisites:
description: Feature IDs. Each feature must evaluate to `true`
type: array
items:
type: string
jsonSchema:
description: Use JSON schema to validate the payload of a JSON-type feature value (enterprise only).
type: string
customFields:
type: object
propertyNames:
type: string
additionalProperties:
type: string
required:
- id
- owner
- valueType
- defaultValue
additionalProperties: false
responses:
'200':
content:
application/json:
schema:
type: object
properties:
feature:
$ref: '#/components/schemas/FeatureV2'
required:
- feature
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v2/features' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v2/features/{id}:
get:
operationId: getFeatureV2
summary: Get a single feature
tags:
- features-v2
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/withRevisions'
responses:
'200':
content:
application/json:
schema:
type: object
properties:
feature:
$ref: '#/components/schemas/FeatureWithRevisionsV2'
required:
- feature
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X GET 'https://api.growthbook.io/api/v2/features/abc123' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
post:
operationId: updateFeatureV2
summary: Partially update a feature
description: 'Updates any combination of a feature''s metadata, default value, environment state, and rules. Other top-level fields are patch-merged: omit a field to leave it unchanged. The `rules` field, when supplied, replaces the entire `rules` array atomically in a single revision (v1 PUT applied per-environment patches; v2 swaps the full flat array). To preserve existing rules during a partial edit, GET the feature first, mutate the returned `rules` array, and PUT the full array back. Safe-rollout rules round-trip via their `safeRolloutId`; use `POST /v2/features/:id/revisions/:version/rules` to create new ones. Returns 403 if approval rules are enabled for an affected environment and the bypass setting is off.'
tags:
- features-v2
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
description:
description: Description of the feature
type: string
archived:
type: boolean
project:
description: An associated project ID
type: string
owner:
description: The userId or email address of the owner. If an email address is provided, it will be used to look up the userId of the matching organization member. If an ID is provided, it will be validated as existing in the organization.
type: string
defaultValue:
type: string
tags:
description: List of associated tags. Will override tags completely with submitted list
type: array
items:
type: string
rules:
description: 'Replaces all feature rules atomically. Behavior differs from v1: v1 PUT applies per-environment patches, v2 PUT swaps the entire `rules` array in one revision. To preserve existing rules during a partial edit, GET the feature first, mutate the returned `rules` array, and PUT the full array back. Safe-rollout rules round-trip via their `safeRolloutId` (creation requires `POST /v2/features/:id/revisions/:version/rules`).'
type: array
items:
anyOf:
- type: object
properties:
description:
type: string
condition:
type: string
savedGroupTargeting:
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
anyOf:
- type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
id:
type: string
enabled:
type: boolean
type:
type: string
const: force
value:
type: string
allEnvironments:
description: When true the rule applies to all environments (default).
type: boolean
environments:
description: Specific environment IDs this rule applies to. Required when allEnvironments is false.
type: array
items:
type: string
required:
- type
- value
additionalProperties: false
- type: object
properties:
description:
type: string
condition:
type: string
savedGroupTargeting:
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
anyOf:
- type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
id:
type: string
enabled:
type: boolean
type:
type: string
const: rollout
value:
type: string
coverage:
type: number
hashAttribute:
type: string
allEnvironments:
description: When true the rule applies to all environments (default).
type: boolean
environments:
description: Specific environment IDs this rule applies to. Required when allEnvironments is false.
type: array
items:
type: string
required:
- type
- value
- coverage
- hashAttribute
additionalProperties: false
- type: object
properties:
description:
type: string
id:
type: string
enabled:
type: boolean
type:
type: string
const: experiment-ref
condition:
type: string
savedGroupTargeting:
# --- truncated at 32 KB (77 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/growthbook/refs/heads/main/openapi/growthbook-features-v2-api-openapi.yml