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: amount: type: number exclusiveMinimum: 0 unit: type: string enum: - weeks - days - hours - minutes required: - amount - unit additionalProperties: false autoRollback: type: boolean rampUpSchedule: type: object properties: enabled: type: boolean steps: minItems: 1 type: array items: type: object properties: percent: type: number minimum: 0 maximum: 1 required: - percent additionalProperties: false required: - enabled additionalProperties: false required: - datasourceId - exposureQueryId - guardrailMetricIds - maxDuration additionalProperties: false required: - type - controlValue - variationValue - hashAttribute - safeRolloutFields 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 enum: - force - rollout value: type: string coverage: type: number minimum: 0 maximum: 1 hashAttribute: type: string seed: type: string required: - value additionalProperties: false rampSchedule: type: object properties: name: type: string templateId: type: string steps: type: array items: type: object properties: trigger: anyOf: - type: object properties: type: type: string const: interval seconds: type: number exclusiveMinimum: 0 required: - type - seconds additionalProperties: false - type: object properties: type: type: string const: approval required: - type additionalProperties: false - type: object properties: type: type: string const: scheduled at: {} required: - type - at additionalProperties: false actions: type: array items: type: object properties: targetType: type: string const: feature-rule targetId: type: string patch: type: object properties: ruleId: type: string coverage: anyOf: - type: number minimum: 0 maximum: 1 - type: 'null' condition: anyOf: - type: string - type: 'null' savedGroups: anyOf: - type: array items: type: object properties: match: type: string enum: - all - none - any ids: type: array items: type: string required: - match - ids additionalProperties: false - type: 'null' prerequisites: anyOf: - type: array items: type: object properties: id: type: string condition: type: string required: - id - condition additionalProperties: false - type: 'null' force: description: Force value (any JSON type) enabled: anyOf: - type: boolean - type: 'null' additionalProperties: false required: - patch additionalProperties: false approvalNotes: anyOf: - type: string - type: 'null' required: - trigger additionalProperties: false endActions: type: array items: type: object properties: targetType: type: string const: feature-rule targetId: type: string patch: type: object properties: ruleId: type: string coverage: anyOf: - type: number minimum: 0 maximum: 1 - type: 'null' condition: anyOf: - type: string - type: 'null' savedGroups: anyOf: - type: array items: type: object properties: match: type: string enum: - all - none - any ids: type: array items: type: string required: - match - ids additionalProperties: false - type: 'null' prerequisites: anyOf: - type: array items: type: object properties: id: type: string condition: type: string required: - id - condition additionalProperties: false - type: 'null' force: description: Force value (any JSON type) enabled: anyOf: - type: boolean - type: 'null' additionalProperties: false required: - patch additionalProperties: false startDate: anyOf: - type: string - type: 'null' endCondition: type: object properties: trigger: anyOf: - type: object properties: type: type: string const: scheduled at: {} required: - type - at additionalProperties: false additionalProperties: false additionalProperties: false schedule: type: object properties: startDate: anyOf: - type: string - type: 'null' endDate: anyOf: - type: string - type: 'null' additionalProperties: false revisionTitle: type: string revisionComment: type: string required: - rule 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}/rules' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" /v2/features/{id}/revisions/{version}/rules/{ruleId}: put: operationId: putFeatureRevisionRuleV2 summary: Update a rule in a draft revision description: Patches fields on an existing rule (identified by `ruleId`). The rule `type` cannot be changed. Scope can be updated via `allEnvironments` / `environments` patch fields. 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 - $ref: '#/components/parameters/ruleId' requestBody: required: true content: application/json: schema: type: object properties: rule: 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: anyOf: - type: array items: type: object properties: timestamp: anyOf: - type: string - type: 'null' enabled: type: boolean required: - timestamp - enabled additionalProperties: false - type: 'null' scheduleType: anyOf: - type: string enum: - none - schedule - ramp - type: 'null' type: type: string enum: - force - rollout - experiment-ref - safe-rollout value: type: string coverage: type: number minimum: 0 maximum: 1 hashAttribute: type: string seed: type: string experimentId: type: string variations: type: array items: type: object properties: variationId: type: string value: type: string required: - variationId - value additionalProperties: false controlValue: type: string variationValue: type: string allEnvironments: type: boolean environments: type: array items: type: string additionalProperties: false rampSchedule: type: object properties: name: type: string templateId: type: string steps: type: array items: type: object properties: trigger: anyOf: - type: object properties: type: type: string const: interval seconds: type: number exclusiveMinimum: 0 required: - type - seconds additionalProperties: false - type: object properties: type: type: string const: approval required: - type additionalProperties: false - type: object properties: type: type: string const: scheduled at: {} required: - type - at additionalProperties: false actions: type: array items: type: object properties: targetType: type: string const: feature-rule targetId: type: string patch: type: object properties: ruleId: type: string coverage: anyOf: - type: number minimum: 0 maximum: 1 - type: 'null' condition: anyOf: - type: string - type: 'null' savedGroups: anyOf: - type: array items: type: object properties: match: type: string enum: - all - none - any ids: type: array items: type: string required: - match - ids additionalProperties: false - type: 'null' prerequisites: anyOf: - type: array items: type: object properties: id: type: string condition: type: string required: - id - condition additionalProperties: false - type: 'null' force: description: Force value (any JSON type) enabled: anyOf: - type: boolean - type: 'null' additionalProperties: false required: - patch additionalProperties: false approvalNotes: anyOf: - type: string - type: 'null' required: - trigger additionalProperties: false endActions: type: array items: type: object properties: targetType: type: string const: feature-rule targetId: type: string patch: type: object properties: ruleId: type: string coverage: anyOf: - type: number minimum: 0 maximum: 1 - type: 'null' condition: anyOf: - type: string - type: 'null' savedGroups: anyOf: - type: array items: type: object properties: match: type: string enum: - all - none - any ids: type: array items: type: string required: - match - ids additionalProperties: false - type: 'null' prerequisites: anyOf: - type: array items: type: object properties: id: type: string condition: type: string required: - id - condition additionalProperties: false - type: 'null' force: description: Force value (any JSON type) enabled: anyOf: - type: boolean - type: 'null' additionalProperties: false required: - patch additionalProperties: false startDate: anyOf: - type: string - type: 'null' endCondition: type: object properties: trigger: anyOf: - type: object properties: type: type: string const: scheduled at: {} required: - type - at additionalProperties: false additionalProperties: false additionalProperties: false schedule: type: object properties: startDate: anyOf: - type: string - type: 'null' endDate: anyOf: - type: string - type: 'null' additionalProperties: false revisionTitle: type: string revisionComment: type: string required: - rule 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}/rules/{ruleId}' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" delete: operationId: deleteFeatureRevisionRuleV2 summary: Delete a rule from a draft revision description: Removes the rule from the revision. Any pending ramp actions for this rule are also cleared. 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 - $ref: '#/components/parameters/ruleId' requestBody: required: true content: application/json: schema: type: object properties: revisionTitle: type: string revisionComment: 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 DELETE 'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/rules/{ruleId}' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" /v2/features/{id}/revisions/{version}/rules/reorder: post: operationId: postFeatureRevisionRulesReorderV2 summary: Reorder rules in the revision description: 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. 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: ruleIds: type: array items: type: string revisionTitle: type: string revisionComment: type: string required: - ruleIds 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}/rules/reorder' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" /v2/features/{id}/revisions/{version}/rules/{ruleId}/ramp-schedule: put: operationId: putFeatureRevisionRuleRampScheduleV2 summary: Set ramp schedule for a rule 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 - $ref: '#/components/parameters/ruleId' requestBody: required: true content: application/json: schema: type: object properties: name: type: string templateId: type: string steps: type: array items: type: object properties: trigger: anyOf: - type: object properties: type: type: string const: interval seconds: type: number exclusiveMinimum: 0 required: - type - seconds additionalProperties: false - type: object properties: type: type: string const: approval required: - type additionalProperties: false - type: object properties: type: type: string const: scheduled at: {} required: - type - at additionalProperties: false actions: type: array items: type: object properties: targetType: type: string const: feature-rule targetId: type: string patch: type: object properties: ruleId: type: string coverage: anyOf: - type: number minimum: 0 maximum: 1 - type: 'null' condition: anyOf: - type: string - type: 'null' savedGroups: anyOf: - type: array items: type: object properties: match: type: string enum: - all - none - any ids: type: array items: type: string required: - match - ids additionalProperties: false - type: 'null' prerequisites: anyOf: - type: array items: type: object properties: id: type: string condition: type: string required: - id - condition additionalProperties: false - type: 'null' force: description: Force value (any JSON type) enabled: anyOf: - type: boolean - type: 'null' additionalProperties: false required: - patch additionalProperties: false approvalNotes: anyOf: - type: string - type: 'null' required: - trigger additionalProperties: false endActions: type: array items: type: object properties: targetType: type: string const: feature-rule targetId: type: string patch: type: object properties: ruleId: type: string coverage: anyOf: - type: number minimum: 0 maximum: 1 - type: 'null' condition: anyOf: - type: string - type: 'null' savedGroups: anyOf: - type: array items: type: object properties: match: type: string enum: - all - none - any ids: type: array items: type: string required: - match - ids additionalProperties: false - type: 'null' prerequisites: anyOf: - type: array items: type: object properties: id: type: string condition: type: string required: - id - condition additionalProperties: false - type: 'null' force: description: Force value (any JSON type) enabled: anyOf: - type: boolean - type: 'null' additionalProperties: false required: - patch additionalProperties: false startDate: anyOf: - type: string - type: 'null' endCondition: type: object properties: trigger: anyOf: - type: object properties: type: type: string const: scheduled at: {} required: - type - at additionalProperties: false additionalProperties: false environment: deprecated: true type: string revisionTitle: type: string revisionComment: 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 PUT 'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/rules/{ruleId}/ramp-schedule' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" delete: operationId: deleteFeatureRevisionRuleRampScheduleV2 summary: Remove ramp schedule from a rule 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 - $ref: '#/components/parameters/ruleId' requestBody: required: true content: application/json: schema: type: object properties: revisionTitle: type: string revisionComment: 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 DELETE 'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/rules/{ruleId}/ramp-schedule' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" /v2/features/{id}/revisions/{version}/request-review: post: operationId: postFeatureRevisionRequestReviewV2 summary: Request review for a draft revision tags: - feature-revisions-v2 parameters: - name: id in: path required: true description: '' schema: type: string - $ref: '#/components/parameters/version' requestBody: required: true content: application/json: schema: type: object properties: comment: 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/{version}/request-review' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" /v2/features/{id}/revisions/{version}/submit-review: post: operationId: postFeatureRevisionSubmitReviewV2 summary: Submit a review on a draft revision tags: - feature-revisions-v2 parameters: - name: id in: path required: true description: '' schema: type: string - $ref: '#/components/parameters/version' requestBody: required: true content: application/json: schema: type: object properties: comment: type: string action: type: string enum: - approve - request-changes - comment 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}/submit-review' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" /v2/features/{id}/revisions/{version}/merge-status: get: operationId: getFeatureRevisionMergeStatusV2 summary: Get merge status for a draft revision 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: success: type: boolean conflicts: type: array items: $ref: '#/components/schemas/conflicts' result: type: object properties: defaultValue: type: string rules: type: array items: {} environmentsEnabled: type: object propertyNames: type: string additionalProperties: type: boolean prerequisites: type: array items: type: object properties: id: type: string condition: type: string required: - id - condition additionalProperties: false archived: type: boolean metadata: type: object properties: releaseType: type: string riskLevel: type: string additionalProperties: {} holdout: anyOf: - type: object properties: id: type: string value: type: string required: - id - value additionalProperties: false - type: 'null' additionalProperties: false required: - success - conflicts additionalProperties: false x-codeSamples: - lang: cURL source: "curl -X GET 'https://api.growthbook.io/api/v2/features/{id}/revisions/{version}/merge-status' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" /v2/features/{id}/revisions/{version}/rebase: post: operationId: postFeatureRevisionRebaseV2 summary: Rebase a draft revision onto the current live version description: '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. Valid keys: `defaultValue`, `rules`, `prerequisites`, `archived`, `holdout`, and `environmentsEnabled.`. Unresolved conflicts respond with `409`.' tags: - feature-revisions-v2 parameters: - name: id in: path required: true description: '' schema: type: string - $ref: '#/components/parameters/version' requestBody: required: true content: application/json: schema: type: object properties: conflictResolutions: type: object propertyNames: type: string additionalProperties: type: string enum: - overwrite - discard 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}/rebase' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" /v2/features/{id}/revisions/{version}/publish: post: operationId: postFeatureRevisionPublishV2 summary: Publish a draft revision description: Immediately publishes a draft revision, making it the live version of the feature. tags: - feature-revisions-v2 parameters: - name: id in: path required: true description: '' schema: type: string - $ref: '#/components/parameters/version' requestBody: required: true content: application/json: schema: type: object properties: comment: 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/{version}/publish' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" /v2/features/{id}/revisions/{version}/discard: post: operationId: postFeatureRevisionDiscardV2 summary: Discard a draft revision tags: - feature-revisions-v2 parameters: - name: id in: path required: true description: '' schema: type: string - $ref: '#/components/parameters/version' requestBody: required: true content: application/json: schema: type: object properties: {} 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}/discard' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" /v2/features/{id}/revisions/{version}/revert: post: operationId: postFeatureRevisionRevertV2 summary: Revert the feature to a prior revision tags: - feature-revisions-v2 parameters: - name: id in: path required: true description: '' schema: type: string - $ref: '#/components/parameters/version' requestBody: required: true content: application/json: schema: type: object properties: strategy: type: string enum: - draft - publish 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/{version}/revert' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" components: parameters: limit: name: limit in: query description: The number of items to return schema: default: 10 description: The number of items to return type: integer minimum: 1 maximum: 100 offset: name: offset in: query description: How many items to skip (use in conjunction with limit for pagination) schema: default: 0 description: How many items to skip (use in conjunction with limit for pagination) type: integer minimum: 0 status: name: status in: query description: '' schema: type: string enum: - draft - published - discarded - approved - changes-requested - pending-review - pending-parent version: name: version in: path required: true description: '' schema: type: integer author: name: author in: query description: '' schema: type: string id: name: id in: path required: true description: The id of the requested resource schema: description: The id of the requested resource type: string ruleId: name: ruleId in: path required: true description: '' schema: type: string skipPagination: name: skipPagination in: query description: '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.' schema: description: '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.' default: false anyOf: - type: string const: 'true' - type: string const: 'false' - type: string const: '0' - type: string const: '1' - type: boolean x-selfHostedOnly: true x-requiresEnv: API_ALLOW_SKIP_PAGINATION featureId: name: featureId in: query description: '' schema: type: string schemas: conflicts: type: object properties: name: type: string key: type: string resolved: type: boolean base: type: string live: type: string revision: type: string required: - name - key - resolved - base - live - revision additionalProperties: false FeatureExperimentRule: allOf: - description: 'Common fields shared by all feature rule types. Specific rule types extend this base with their own required properties (value, coverage, etc.). ' type: object properties: description: type: string condition: type: string id: type: string enabled: type: boolean scheduleRules: description: Simple time-based on/off schedule for this rule type: array items: $ref: '#/components/schemas/ScheduleRule' scheduleType: description: 'UI hint for which scheduling mode is active: - `none` – no schedule - `schedule` – simple time-based enable/disable via `scheduleRules` - `ramp` – multi-step ramp-up controlled by an associated RampSchedule document ' type: string enum: - none - schedule - ramp 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 of the prerequisite type: string condition: type: string required: - id - condition additionalProperties: false required: - description - id - enabled additionalProperties: false - type: object properties: 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 minimum: 0 maximum: 1 value: description: Variation values with weights type: array items: type: object properties: value: type: string weight: type: number name: type: string required: - value - weight additionalProperties: false required: - type additionalProperties: false FeatureRolloutRule: allOf: - description: 'Common fields shared by all feature rule types. Specific rule types extend this base with their own required properties (value, coverage, etc.). ' type: object properties: description: type: string condition: type: string id: type: string enabled: type: boolean scheduleRules: description: Simple time-based on/off schedule for this rule type: array items: $ref: '#/components/schemas/ScheduleRule' scheduleType: description: 'UI hint for which scheduling mode is active: - `none` – no schedule - `schedule` – simple time-based enable/disable via `scheduleRules` - `ramp` – multi-step ramp-up controlled by an associated RampSchedule document ' type: string enum: - none - schedule - ramp 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 of the prerequisite type: string condition: type: string required: - id - condition additionalProperties: false required: - description - id - enabled additionalProperties: false - type: object properties: type: type: string const: rollout value: type: string coverage: type: number minimum: 0 maximum: 1 hashAttribute: type: string seed: description: Optional seed for the hash function; defaults to the rule id type: string required: - type - value - coverage - hashAttribute additionalProperties: false FeatureRuleV2: allOf: - $ref: '#/components/schemas/FeatureRule' - type: object properties: allEnvironments: description: When true the rule applies to all environments. When false only the environments listed in `environments` receive the rule. type: boolean environments: description: The environment IDs this rule is active in. Populated when `allEnvironments` is false. type: array items: type: string required: - allEnvironments additionalProperties: false FeatureRule: anyOf: - $ref: '#/components/schemas/FeatureForceRule' - $ref: '#/components/schemas/FeatureRolloutRule' - $ref: '#/components/schemas/FeatureExperimentRule' - $ref: '#/components/schemas/FeatureExperimentRefRule' - $ref: '#/components/schemas/FeatureSafeRolloutRule' FeatureSafeRolloutRule: allOf: - description: 'Common fields shared by all feature rule types. Specific rule types extend this base with their own required properties (value, coverage, etc.). ' type: object properties: description: type: string condition: type: string id: type: string enabled: type: boolean scheduleRules: description: Simple time-based on/off schedule for this rule type: array items: $ref: '#/components/schemas/ScheduleRule' scheduleType: description: 'UI hint for which scheduling mode is active: - `none` – no schedule - `schedule` – simple time-based enable/disable via `scheduleRules` - `ramp` – multi-step ramp-up controlled by an associated RampSchedule document ' type: string enum: - none - schedule - ramp 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 of the prerequisite type: string condition: type: string required: - id - condition additionalProperties: false required: - description - id - enabled additionalProperties: false - type: object properties: type: type: string const: safe-rollout controlValue: type: string variationValue: type: string seed: type: string hashAttribute: type: string trackingKey: type: string safeRolloutId: type: string status: type: string enum: - running - released - rolled-back - stopped required: - type - controlValue - variationValue additionalProperties: false FeatureExperimentRefRule: allOf: - description: 'Common fields shared by all feature rule types. Specific rule types extend this base with their own required properties (value, coverage, etc.). ' type: object properties: description: type: string condition: type: string id: type: string enabled: type: boolean scheduleRules: description: Simple time-based on/off schedule for this rule type: array items: $ref: '#/components/schemas/ScheduleRule' scheduleType: description: 'UI hint for which scheduling mode is active: - `none` – no schedule - `schedule` – simple time-based enable/disable via `scheduleRules` - `ramp` – multi-step ramp-up controlled by an associated RampSchedule document ' type: string enum: - none - schedule - ramp 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 of the prerequisite type: string condition: type: string required: - id - condition additionalProperties: false required: - description - id - enabled additionalProperties: false - type: object properties: type: type: string const: experiment-ref 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 ScheduleRule: type: object properties: enabled: description: Whether the rule should be enabled or disabled at the specified timestamp. type: boolean timestamp: description: ISO timestamp when the rule should activate. anyOf: - format: date-time type: string - type: 'null' required: - enabled - timestamp additionalProperties: false FeatureForceRule: allOf: - description: 'Common fields shared by all feature rule types. Specific rule types extend this base with their own required properties (value, coverage, etc.). ' type: object properties: description: type: string condition: type: string id: type: string enabled: type: boolean scheduleRules: description: Simple time-based on/off schedule for this rule type: array items: $ref: '#/components/schemas/ScheduleRule' scheduleType: description: 'UI hint for which scheduling mode is active: - `none` – no schedule - `schedule` – simple time-based enable/disable via `scheduleRules` - `ramp` – multi-step ramp-up controlled by an associated RampSchedule document ' type: string enum: - none - schedule - ramp 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 of the prerequisite type: string condition: type: string required: - id - condition additionalProperties: false required: - description - id - enabled additionalProperties: false - type: object properties: type: type: string const: force value: type: string required: - type - value additionalProperties: false FeatureRevisionV2: type: object properties: featureId: description: The feature this revision belongs to type: string baseVersion: type: integer version: type: integer comment: type: string date: format: date-time type: string status: type: string createdBy: type: string publishedBy: type: string defaultValue: description: The default value at the time this revision was created type: string rules: description: Unified rules array. Each rule carries its own environment scope via `allEnvironments` / `environments`. type: array items: $ref: '#/components/schemas/FeatureRuleV2' definitions: type: object propertyNames: type: string additionalProperties: description: A JSON stringified [FeatureDefinition](#tag/FeatureDefinition_model) type: string environmentsEnabled: description: Per-environment enabled state captured in this revision (only present when kill-switch gating is enabled) type: object propertyNames: type: string additionalProperties: type: boolean envPrerequisites: description: Per-environment prerequisites captured in this revision (only present when prerequisite gating is enabled) type: object propertyNames: type: string additionalProperties: type: array items: type: object properties: id: description: Feature ID type: string condition: type: string required: - id - condition additionalProperties: false prerequisites: description: Feature-level prerequisites captured in this revision (only present when prerequisite gating is enabled) type: array items: type: object properties: id: description: Feature ID type: string condition: type: string required: - id - condition additionalProperties: false metadata: description: Metadata fields captured in this revision (only present when metadata gating is enabled) type: object properties: description: type: string owner: description: The userId of the owner (or raw owner name/email for legacy records) type: string project: type: string tags: type: array items: type: string neverStale: type: boolean valueType: type: string jsonSchema: type: object properties: schemaType: type: string enum: - schema - simple schema: type: string simple: type: object propertyNames: type: string additionalProperties: {} date: format: date-time type: string enabled: type: boolean additionalProperties: false customFields: type: object propertyNames: type: string additionalProperties: {} additionalProperties: false required: - featureId - baseVersion - version - comment - date - status - rules additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer description: 'If using Bearer auth, pass the Secret Key as the token: ```bash curl https://api.growthbook.io/api/v1/features -H "Authorization: Bearer secret_abc123DEF456" ``` ' basicAuth: type: http scheme: basic description: 'If using HTTP Basic auth, pass the Secret Key as the username and leave the password blank: ```bash curl https://api.growthbook.io/api/v1/features -u secret_abc123DEF456: # The ":" at the end stops curl from asking for a password ``` ' x-tagGroups: - name: Endpoints tags: - projects - environments - features-v2 - feature-revisions-v2 - features - feature-revisions - ramp-schedules - data-sources - fact-tables - fact-metrics - metrics - experiments - namespaces - snapshots - dimensions - segments - sdk-connections - visual-changesets - saved-groups - organizations - members - code-references - archetypes - queries - settings - attributes - usage - Dashboards - CustomFields - MetricGroups - Teams - ExperimentTemplates - AnalyticsExplorations - RampScheduleTemplates - name: Models tags: - AnalyticsExploration_model - Archetype_model - Attribute_model - CodeRef_model - CustomField_model - Dashboard_model - DataSource_model - Dimension_model - Environment_model - Experiment_model - ExperimentAnalysisSettings_model - ExperimentDecisionFrameworkSettings_model - ExperimentMetric_model - ExperimentMetricOverrideEntry_model - ExperimentResults_model - ExperimentSnapshot_model - ExperimentTemplate_model - ExperimentWithEnhancedStatus_model - FactMetric_model - FactTable_model - FactTableColumn_model - FactTableFilter_model - Feature_model - FeatureBaseRule_model - FeatureDefinition_model - FeatureEnvironment_model - FeatureEnvironmentV2_model - FeatureExperimentRefRule_model - FeatureExperimentRule_model - FeatureForceRule_model - FeatureRevision_model - FeatureRevisionV2_model - FeatureRolloutRule_model - FeatureRule_model - FeatureRuleV2_model - FeatureSafeRolloutRule_model - FeatureV2_model - FeatureWithRevisions_model - FeatureWithRevisionsV2_model - InformationSchema_model - InformationSchemaTable_model - LookbackOverride_model - Member_model - Metric_model - MetricAnalysis_model - MetricGroup_model - MetricUsage_model - Namespace_model - NamespaceExperimentMember_model - Organization_model - PaginationFields_model - Project_model - Query_model - RampSchedule_model - RampScheduleTemplate_model - SavedGroup_model - ScheduleRule_model - SdkConnection_model - Segment_model - Settings_model - Team_model - VisualChange_model - VisualChangeset_model