GrowthBook features API
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.
OpenAPI Specification
openapi: 3.1.0
info:
version: 1.0.0
title: GrowthBook REST AnalyticsExplorations features 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
x-displayName: Feature Flags (legacy)
description: 'Control your feature flags programatically.
**These are v1 endpoints.** New integrations should use the v2 Feature Flags endpoints, which expose a unified per-rule environment scope instead of per-environment rule arrays.'
paths:
/v1/features:
get:
operationId: listFeatures
summary: Get all features
description: '**Deprecated.** Use [GET /v2/features](#operation/listFeaturesV2) instead.
Returns features with pagination. The skipPagination query parameter is
honored only when API_ALLOW_SKIP_PAGINATION is set (self-hosted deployments).
'
deprecated: true
tags:
- features
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/projectId'
- $ref: '#/components/parameters/clientKey'
- $ref: '#/components/parameters/skipPagination'
responses:
'200':
content:
application/json:
schema:
allOf:
- type: object
properties:
features:
type: array
items:
$ref: '#/components/schemas/Feature'
required:
- features
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: "curl -X GET 'https://api.growthbook.io/api/v1/features' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
post:
operationId: postFeature
summary: Create a single feature
description: '**Deprecated.** Use [POST /v2/features](#operation/postFeatureV2) instead.'
deprecated: true
tags:
- features
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
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
environments:
description: 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.
type: object
propertyNames:
type: string
additionalProperties:
type: object
properties:
enabled:
type: boolean
rules:
type: array
items:
anyOf:
- type: object
properties:
description:
type: string
condition:
description: Applied to everyone by default.
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:
$ref: '#/components/schemas/ScheduleRule'
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: force
value:
type: string
required:
- type
- value
additionalProperties: false
- type: object
properties:
description:
type: string
condition:
description: Applied to everyone by default.
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:
$ref: '#/components/schemas/ScheduleRule'
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: rollout
value:
type: string
coverage:
description: Percent of traffic included in this experiment. Users not included in the experiment will skip this rule.
type: number
hashAttribute:
type: string
required:
- type
- value
- coverage
- hashAttribute
additionalProperties: false
- type: object
properties:
description:
type: string
id:
type: string
enabled:
description: Enabled by default
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:
$ref: '#/components/schemas/ScheduleRule'
variations:
type: array
items:
type: object
properties:
value:
type: string
variationId:
type: string
required:
- value
- variationId
additionalProperties: false
experimentId:
type: string
required:
- type
- variations
- experimentId
additionalProperties: false
- type: object
properties:
description:
type: string
condition:
type: string
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: experiment
trackingKey:
type: string
hashAttribute:
type: string
fallbackAttribute:
type: string
disableStickyBucketing:
type: boolean
bucketVersion:
type: number
minBucketVersion:
type: number
namespace:
type: object
properties:
enabled:
type: boolean
name:
type: string
range:
minItems: 2
maxItems: 2
type: array
items:
type: number
required:
- enabled
- name
- range
additionalProperties: false
coverage:
type: number
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
$ref: '#/components/schemas/ScheduleRule'
values:
type: array
items:
type: object
properties:
value:
type: string
weight:
type: number
name:
type: string
required:
- value
- weight
additionalProperties: false
value:
deprecated: true
description: Support passing values under the value key as that was the original spec for FeatureExperimentRules
type: array
items:
type: object
properties:
value:
type: string
weight:
type: number
name:
type: string
required:
- value
- weight
additionalProperties: false
required:
- condition
- type
additionalProperties: false
definition:
description: A JSON stringified [FeatureDefinition](#tag/FeatureDefinition_model)
type: string
draft:
description: Use to write draft changes without publishing them.
type: object
properties:
enabled:
type: boolean
rules:
type: array
items:
anyOf:
- type: object
properties:
description:
type: string
condition:
description: Applied to everyone by default.
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:
$ref: '#/components/schemas/ScheduleRule'
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: force
value:
type: string
required:
- type
- value
additionalProperties: false
- type: object
properties:
description:
type: string
condition:
description: Applied to everyone by default.
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:
$ref: '#/components/schemas/ScheduleRule'
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: rollout
value:
type: string
coverage:
description: Percent of traffic included in this experiment. Users not included in the experiment will skip this rule.
type: number
hashAttribute:
type: string
required:
- type
- value
- coverage
- hashAttribute
additionalProperties: false
- type: object
properties:
description:
type: string
id:
type: string
enabled:
description: Enabled by default
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:
$ref: '#/components/schemas/ScheduleRule'
variations:
type: array
items:
type: object
properties:
value:
type: string
variationId:
type: string
required:
- value
- variationId
additionalProperties: false
experimentId:
type: string
required:
- type
- variations
- experimentId
additionalProperties: false
- type: object
properties:
description:
type: string
condition:
type: string
id:
type: string
enabled:
description: Enabled by default
type: boolean
type:
type: string
const: experiment
trackingKey:
type: string
hashAttribute:
type: string
fallbackAttribute:
type: string
disableStickyBucketing:
type: boolean
bucketVersion:
type: number
minBucketVersion:
type: number
namespace:
type: object
properties:
# --- truncated at 32 KB (109 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/growthbook/refs/heads/main/openapi/growthbook-features-api-openapi.yml