GrowthBook feature-revisions-v2 API
Draft revisions for feature flags, including rules, scheduling, and approval workflows. Revision `rules` is a flat array with per-rule scope fields.
OpenAPI Specification
openapi: 3.1.0
info:
version: 1.0.0
title: GrowthBook REST AnalyticsExplorations feature-revisions-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: feature-revisions-v2
x-displayName: Feature Revisions
description: 'Draft revisions for feature flags, including rules, scheduling, and approval workflows.
Revision `rules` is a flat array with per-rule scope fields.'
paths:
/v2/revisions:
get:
operationId: listRevisionsV2
summary: List feature revisions
description: Returns a paginated list of feature revisions across all features in the organization. Revision `rules` is a flat array with per-rule scope.
tags:
- feature-revisions-v2
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/skipPagination'
- $ref: '#/components/parameters/featureId'
- $ref: '#/components/parameters/status'
- $ref: '#/components/parameters/author'
- name: mine
in: query
description: If true, return only revisions authored by or contributed to by the calling user.
schema:
description: If true, return only revisions authored by or contributed to by the calling user.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
responses:
'200':
content:
application/json:
schema:
type: object
properties:
revisions:
type: array
items:
$ref: '#/components/schemas/FeatureRevisionV2'
limit:
type: integer
offset:
type: integer
count:
type: integer
total:
type: integer
hasMore:
type: boolean
nextOffset:
anyOf:
- type: integer
- type: 'null'
required:
- revisions
- limit
- offset
- count
- total
- hasMore
- nextOffset
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X GET 'https://api.growthbook.io/api/v2/revisions' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v2/features/{id}/revisions:
get:
operationId: getFeatureRevisionsV2
summary: List revisions for a feature
description: Returns a paginated list of revisions for this feature, sorted newest-first. Revision `rules` is a flat array with per-rule scope.
tags:
- feature-revisions-v2
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/skipPagination'
- $ref: '#/components/parameters/status'
- $ref: '#/components/parameters/author'
responses:
'200':
content:
application/json:
schema:
type: object
properties:
revisions:
type: array
items:
$ref: '#/components/schemas/FeatureRevisionV2'
limit:
type: integer
offset:
type: integer
count:
type: integer
total:
type: integer
hasMore:
type: boolean
nextOffset:
anyOf:
- type: integer
- type: 'null'
required:
- revisions
- limit
- offset
- count
- total
- hasMore
- nextOffset
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X GET 'https://api.growthbook.io/api/v2/features/{id}/revisions' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
post:
operationId: postFeatureRevisionV2
summary: Create a draft revision
description: Creates a new draft revision branched from the current live revision.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
comment:
type: string
title:
type: string
additionalProperties: false
responses:
'200':
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v2/features/{id}/revisions' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v2/features/{id}/revisions/latest:
get:
operationId: getFeatureRevisionLatestV2
summary: Get the most recent active draft revision
description: Returns the most recently updated draft revision for the feature. Returns 404 if there is no active draft.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- name: mine
in: query
description: If true, return only the most recent active draft authored by or contributed to by the calling user.
schema:
description: If true, return only the most recent active draft authored by or contributed to by the calling user.
anyOf:
- type: string
const: 'true'
- type: string
const: 'false'
- type: string
const: '0'
- type: string
const: '1'
- type: boolean
responses:
'200':
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X GET 'https://api.growthbook.io/api/v2/features/{id}/revisions/latest' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v2/features/{id}/revisions/{version}:
get:
operationId: getFeatureRevisionV2
summary: Get a single feature revision
description: Returns the revision at the specified version for this feature. Revision `rules` is a flat array with per-rule environment scope.
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- $ref: '#/components/parameters/version'
responses:
'200':
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X GET 'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v2/features/{id}/revisions/{version}/metadata:
put:
operationId: putFeatureRevisionMetadataV2
summary: Update revision metadata
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- name: version
in: path
required: true
description: ''
schema:
anyOf:
- type: integer
- type: string
const: new
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
comment:
type: string
title:
type: string
description:
type: string
owner:
description: The userId or email address of the owner. If an email address is provided, it will be used to look up the userId of the matching organization member. If an ID is provided, it will be validated as existing in the organization.
type: string
project:
type: string
tags:
type: array
items:
type: string
neverStale:
type: boolean
customFields:
type: object
propertyNames:
type: string
additionalProperties: {}
jsonSchema:
type: object
properties:
schemaType:
type: string
enum:
- schema
- simple
schema:
type: string
simple:
type: object
properties:
type:
type: string
enum:
- object
- object[]
- primitive
- primitive[]
fields:
type: array
items:
type: object
properties:
key:
type: string
maxLength: 64
type:
type: string
enum:
- integer
- float
- string
- boolean
required:
type: boolean
default:
type: string
maxLength: 256
description:
type: string
maxLength: 256
enum:
maxItems: 256
type: array
items:
type: string
maxLength: 256
min:
type: number
max:
type: number
required:
- key
- type
- required
- default
- description
- enum
- min
- max
additionalProperties: false
required:
- type
- fields
additionalProperties: false
date: {}
enabled:
type: boolean
required:
- schemaType
- schema
- simple
- date
- enabled
additionalProperties: false
additionalProperties: false
responses:
'200':
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X PUT 'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/metadata' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v2/features/{id}/revisions/{version}/default-value:
put:
operationId: putFeatureRevisionDefaultValueV2
summary: Set the default value in a draft revision
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- name: version
in: path
required: true
description: ''
schema:
anyOf:
- type: integer
- type: string
const: new
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
defaultValue:
type: string
revisionTitle:
type: string
revisionComment:
type: string
required:
- defaultValue
additionalProperties: false
responses:
'200':
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X PUT 'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/default-value' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v2/features/{id}/revisions/{version}/prerequisites:
put:
operationId: putFeatureRevisionPrerequisitesV2
summary: Set feature-level prerequisites in a draft revision
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- name: version
in: path
required: true
description: ''
schema:
anyOf:
- type: integer
- type: string
const: new
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
revisionTitle:
type: string
revisionComment:
type: string
required:
- prerequisites
additionalProperties: false
responses:
'200':
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X PUT 'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/prerequisites' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v2/features/{id}/revisions/{version}/holdout:
put:
operationId: putFeatureRevisionHoldoutV2
summary: Set holdout in a draft revision
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- name: version
in: path
required: true
description: ''
schema:
anyOf:
- type: integer
- type: string
const: new
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
holdout:
anyOf:
- type: object
properties:
id:
type: string
value:
type: string
required:
- id
- value
additionalProperties: false
- type: 'null'
revisionTitle:
type: string
revisionComment:
type: string
required:
- holdout
additionalProperties: false
responses:
'200':
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X PUT 'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/holdout' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v2/features/{id}/revisions/{version}/archive:
put:
operationId: putFeatureRevisionArchiveV2
summary: Set archived state in a draft revision
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- name: version
in: path
required: true
description: ''
schema:
anyOf:
- type: integer
- type: string
const: new
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
archived:
type: boolean
revisionTitle:
type: string
revisionComment:
type: string
required:
- archived
additionalProperties: false
responses:
'200':
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X PUT 'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/archive' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v2/features/{id}/revisions/{version}/toggle:
post:
operationId: postFeatureRevisionToggleV2
summary: Toggle an environment on/off in a draft revision
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- name: version
in: path
required: true
description: ''
schema:
anyOf:
- type: integer
- type: string
const: new
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
environment:
type: string
enabled:
type: boolean
revisionTitle:
type: string
revisionComment:
type: string
required:
- environment
- enabled
additionalProperties: false
responses:
'200':
content:
application/json:
schema:
type: object
properties:
revision:
$ref: '#/components/schemas/FeatureRevisionV2'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/toggle' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v2/features/{id}/revisions/{version}/rules:
post:
operationId: postFeatureRevisionRuleAddV2
summary: Add a rule to a draft revision
description: 'Appends a new rule to the revision''s rule list. Supply `allEnvironments: true` to target all environments, or `environments: [...]` to scope to specific ones. Use `rampSchedule` for ramp configuration or `schedule` for a simple start/end window.'
tags:
- feature-revisions-v2
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
- name: version
in: path
required: true
description: ''
schema:
anyOf:
- type: integer
- type: string
const: new
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
rule:
anyOf:
- type: object
properties:
description:
type: string
enabled:
type: boolean
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
anyOf:
- type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
scheduleType:
type: string
enum:
- none
- schedule
- ramp
allEnvironments:
description: When true the rule applies to all environments. Defaults to false.
type: boolean
environments:
description: Specific environment IDs this rule applies to. Used when allEnvironments is false.
type: array
items:
type: string
type:
type: string
const: experiment-ref
experimentId:
type: string
variations:
type: array
items:
type: object
properties:
variationId:
type: string
value:
type: string
required:
- value
additionalProperties: false
required:
- type
- experimentId
- variations
additionalProperties: false
- type: object
properties:
description:
type: string
enabled:
type: boolean
condition:
type: string
savedGroups:
type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
prerequisites:
type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
scheduleRules:
type: array
items:
type: object
properties:
timestamp:
anyOf:
- type: string
- type: 'null'
enabled:
type: boolean
required:
- timestamp
- enabled
additionalProperties: false
scheduleType:
type: string
enum:
- none
- schedule
- ramp
allEnvironments:
description: When true the rule applies to all environments. Defaults to false.
type: boolean
environments:
description: Specific environment IDs this rule applies to. Used when allEnvironments is false.
type: array
items:
type: string
type:
type: string
const: safe-rollout
controlValue:
type: string
variationValue:
type: string
hashAttribute:
type: string
trackingKey:
type: string
seed:
type: string
safeRolloutFields:
type: object
properties:
datasourceId:
type: string
exposureQueryId:
type: string
guardrailMetricIds:
type: array
items:
type: string
maxDuration:
type: object
properties:
# --- truncated at 32 KB (113 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/growthbook/refs/heads/main/openapi/growthbook-feature-revisions-v2-api-openapi.yml