GrowthBook feature-revisions API
Draft revisions for feature flags, including rules, scheduling, and approval workflows. **These are v1 endpoints.** New integrations should use the v2 Feature Revisions endpoints.
OpenAPI Specification
openapi: 3.1.0
info:
version: 1.0.0
title: GrowthBook REST AnalyticsExplorations feature-revisions 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
x-displayName: Feature Revisions (legacy)
description: 'Draft revisions for feature flags, including rules, scheduling, and approval workflows.
**These are v1 endpoints.** New integrations should use the v2 Feature Revisions endpoints.'
paths:
/v1/revisions:
get:
operationId: listRevisions
summary: List feature revisions
description: '**Deprecated.** Use [GET /v2/revisions](#operation/listRevisionsV2) 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.'
deprecated: true
tags:
- feature-revisions
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'
- $ref: '#/components/parameters/mine'
responses:
'200':
content:
application/json:
schema:
type: object
properties:
revisions:
type: array
items:
$ref: '#/components/schemas/FeatureRevision'
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/v1/revisions' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/features/{id}/revisions:
get:
operationId: getFeatureRevisions
summary: List revisions for a feature
description: '**Deprecated.** Use [GET /v2/features/:id/revisions](#operation/getFeatureRevisionsV2) instead.
Returns a paginated list of revisions for this feature, sorted newest-first. Optionally filtered by status and/or author.'
deprecated: true
tags:
- feature-revisions
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/FeatureRevision'
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/v1/features/abc123/revisions' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
post:
operationId: postFeatureRevision
summary: Create a draft revision
description: '**Deprecated.** Use [POST /v2/features/:id/revisions](#operation/postFeatureRevisionV2) 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.'
deprecated: true
tags:
- feature-revisions
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/FeatureRevision'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v1/features/{id}/revisions' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/features/{id}/revisions/latest:
get:
operationId: getFeatureRevisionLatest
summary: Get the most recent active draft revision
description: '**Deprecated.** Use [GET /v2/features/:id/revisions/latest](#operation/getFeatureRevisionLatestV2) 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).'
deprecated: true
tags:
- feature-revisions
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. Requires a user-scoped API key.
schema:
description: If true, return only the most recent active draft authored by or contributed to by the calling user. Requires a user-scoped API key.
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/FeatureRevision'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X GET 'https://api.growthbook.io/api/v1/features/{id}/revisions/latest' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/features/{id}/revisions/{version}:
get:
operationId: getFeatureRevision
summary: Get a single feature revision
description: '**Deprecated.** Use [GET /v2/features/:id/revisions/:version](#operation/getFeatureRevisionV2) instead.
Returns the revision at the specified version for this feature. Use `GET /features/{id}/revisions/latest` for the most recent active draft.'
deprecated: true
tags:
- feature-revisions
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/FeatureRevision'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X GET 'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/features/{id}/revisions/{version}/metadata:
put:
operationId: putFeatureRevisionMetadata
summary: Update revision metadata (comment, title, feature metadata)
description: '**Deprecated.** Use [PUT /v2/features/:id/revisions/:version/metadata](#operation/putFeatureRevisionMetadataV2) 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.'
deprecated: true
tags:
- feature-revisions
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/FeatureRevision'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X PUT 'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/metadata' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/features/{id}/revisions/{version}/default-value:
put:
operationId: putFeatureRevisionDefaultValue
summary: Set the default value in a draft revision
description: '**Deprecated.** Use [PUT /v2/features/:id/revisions/:version/default-value](#operation/putFeatureRevisionDefaultValueV2) 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).'
deprecated: true
tags:
- feature-revisions
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/FeatureRevision'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X PUT 'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/default-value' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/features/{id}/revisions/{version}/prerequisites:
put:
operationId: putFeatureRevisionPrerequisites
summary: Set feature-level prerequisites in a draft revision
description: '**Deprecated.** Use [PUT /v2/features/:id/revisions/:version/prerequisites](#operation/putFeatureRevisionPrerequisitesV2) 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.'
deprecated: true
tags:
- feature-revisions
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/FeatureRevision'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X PUT 'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/prerequisites' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/features/{id}/revisions/{version}/holdout:
put:
operationId: putFeatureRevisionHoldout
summary: Set holdout in a draft revision
description: '**Deprecated.** Use [PUT /v2/features/:id/revisions/:version/holdout](#operation/putFeatureRevisionHoldoutV2) 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.'
deprecated: true
tags:
- feature-revisions
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/FeatureRevision'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X PUT 'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/holdout' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/features/{id}/revisions/{version}/archive:
put:
operationId: putFeatureRevisionArchive
summary: Set archived state in a draft revision
description: '**Deprecated.** Use [PUT /v2/features/:id/revisions/:version/archive](#operation/putFeatureRevisionArchiveV2) instead.
Sets whether the feature is archived. Archived features are excluded from SDK payloads on publish.'
deprecated: true
tags:
- feature-revisions
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/FeatureRevision'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X PUT 'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/archive' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/features/{id}/revisions/{version}/toggle:
post:
operationId: postFeatureRevisionToggle
summary: Toggle an environment on/off in a draft revision
description: '**Deprecated.** Use [POST /v2/features/:id/revisions/:version/toggle](#operation/postFeatureRevisionToggleV2) instead.
Sets whether the feature is enabled in the given environment as part of the draft. Takes effect on publish.'
deprecated: true
tags:
- feature-revisions
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/FeatureRevision'
required:
- revision
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v1/features/{id}/revisions/{version}/toggle' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/features/{id}/revisions/{version}/rules:
post:
operationId: postFeatureRevisionRuleAdd
summary: Add a rule to a draft revision
description: '**Deprecated.** Use [POST /v2/features/:id/revisions/:version/rules](#operation/postFeatureRevisionRuleAddV2) 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.'
deprecated: true
tags:
- feature-revisions
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
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
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
# --- truncated at 32 KB (136 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/growthbook/refs/heads/main/openapi/growthbook-feature-revisions-api-openapi.yml