GrowthBook ramp-schedules API
Multi-step rollout schedules that gradually ramp feature rule changes over time, with support for interval, approval, and scheduled triggers.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/growthbook-ramp-schedules-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.1.0
info:
version: 1.0.0
title: GrowthBook REST AnalyticsExplorations ramp-schedules 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: ramp-schedules
x-displayName: Ramp Schedules
description: Multi-step rollout schedules that gradually ramp feature rule changes over time, with support for interval, approval, and scheduled triggers.
paths:
/v1/ramp-schedules:
get:
operationId: listRampSchedules
summary: Get all rampSchedules
description: 'Returns all ramp schedules for the organization, with optional filters.
'
tags:
- ramp-schedules
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/featureId'
- name: status
in: query
description: Filter by schedule status
schema:
description: Filter by schedule status
type: string
enum:
- pending
- ready
- running
- paused
- pending-approval
- completed
- rolled-back
responses:
'200':
content:
application/json:
schema:
type: object
properties:
limit:
type: integer
offset:
type: integer
count:
type: integer
total:
type: integer
hasMore:
type: boolean
nextOffset:
anyOf:
- type: integer
- type: 'null'
rampSchedules:
type: array
items:
$ref: '#/components/schemas/RampSchedule'
required:
- limit
- offset
- count
- total
- hasMore
- nextOffset
- rampSchedules
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X GET 'https://api.growthbook.io/api/v1/ramp-schedules' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
post:
operationId: createRampSchedule
summary: Create a single rampSchedule
description: 'Creates a new ramp schedule, optionally attaching it to a published feature rule.
### Target attachment (optional)
Provide `featureId` and `ruleId` together to attach the schedule to a specific
rule on creation. The rule must already be live (published). Each rule can only
be controlled by one schedule at a time.
When both are supplied, **`targetId` and `patch.ruleId` are auto-injected**
into every step action and endAction — callers only need to supply the patch
values (`coverage`, `condition`, etc.).
`environment` is accepted for backward compatibility with pre-v2 ramps but is
deprecated and no longer required. Post-v2 `rule.id` is uniquely sufficient.
If rule attachment is omitted, the schedule is created as a free-standing
skeleton in `pending` status. Use `POST /ramp-schedules/{id}/actions/add-target`
to attach rules later, and `POST /ramp-schedules/{id}/actions/start` to start it.
### Using templates
Provide `templateId` to inherit steps and endActions from a saved template.
Explicit `steps` / `endActions` in the request body take precedence over the
template. Template auto-population requires `featureId` and `ruleId` to be set
(so targetId can be injected).
Requires an **Enterprise** plan.
'
tags:
- ramp-schedules
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
featureId:
description: Feature that anchors this schedule. Required when `ruleId` is set.
type: string
ruleId:
description: Rule to attach as the initial target. Requires `featureId`. Post-v2 `rule.id` is uniquely sufficient; `environment` is optional and deprecated.
type: string
environment:
deprecated: true
description: Deprecated. Legacy disambiguator for pre-v2 rules whose `ruleId` could repeat across envs. Omit on new schedules — the resolver uses `rule.id` directly.
type: string
steps:
description: 'Ordered ramp steps. When `featureId`+`ruleId` are provided,
`targetId` and `patch.ruleId` in actions are auto-injected — only
supply the patch fields you want to change.
'
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:
type: string
required:
- type
- at
additionalProperties: false
actions:
type: array
items:
type: object
properties:
targetType:
description: Omit when using featureId+ruleId+environment (auto-injected)
type: string
const: feature-rule
targetId:
description: Auto-injected when featureId+ruleId+environment are provided
type: string
patch:
description: Sparse patch — only fields present are applied; absent fields accumulate from previous steps
type: object
properties:
ruleId:
description: Auto-injected when ruleId is provided at the top level
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:
description: Actions applied when the ramp completes. `targetId` and `patch.ruleId` are auto-injected when `featureId`+`ruleId` are provided.
type: array
items:
type: object
properties:
targetType:
description: Omit when using featureId+ruleId+environment (auto-injected)
type: string
const: feature-rule
targetId:
description: Auto-injected when featureId+ruleId+environment are provided
type: string
patch:
description: Sparse patch — only fields present are applied; absent fields accumulate from previous steps
type: object
properties:
ruleId:
description: Auto-injected when ruleId is provided at the top level
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:
description: When to start. Absent/null = immediately on start action.
anyOf:
- type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
- type: 'null'
endCondition:
description: Optional hard deadline
type: object
properties:
trigger:
type: object
properties:
type:
type: string
const: scheduled
at:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
required:
- type
- at
additionalProperties: false
additionalProperties: false
templateId:
description: Load steps and endActions from a saved template (featureId+ruleId must also be set for auto-injection)
type: string
required:
- name
additionalProperties: false
responses:
'200':
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v1/ramp-schedules' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/ramp-schedules/{id}/actions/start:
post:
operationId: startRampSchedule
summary: Start a ramp schedule
description: 'Transitions the schedule from `ready` to `running` and processes the first
step immediately if eligible.
'
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/start' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/ramp-schedules/{id}/actions/pause:
post:
operationId: pauseRampSchedule
summary: Pause a ramp schedule
description: 'Pauses a `running` or `pending-approval` schedule. The schedule can be
resumed from the same position with the `/actions/resume` endpoint.
'
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/pause' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/ramp-schedules/{id}/actions/resume:
post:
operationId: resumeRampSchedule
summary: Resume a paused ramp schedule
description: 'Resumes a `paused` schedule. Adjusts timing anchors to account for the
pause duration so step intervals continue from where they left off.
'
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/resume' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/ramp-schedules/{id}/actions/rollback:
post:
operationId: rollbackRampSchedule
summary: Roll back a ramp schedule
description: 'Rolls back to the starting position and lands in `paused` status so the
schedule can be restarted with `/actions/start` or `/actions/resume`.
'
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/rollback' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/ramp-schedules/{id}/actions/jump:
post:
operationId: jumpRampSchedule
summary: Jump to a specific step
description: 'Moves the schedule directly to `targetStepIndex` (forward or backward) and
pauses. Use `-1` to jump to the pre-start position without rolling back rule
patches.
'
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
targetStepIndex:
description: Zero-based index of the step to jump to; -1 = pre-start
type: integer
minimum: -1
required:
- targetStepIndex
additionalProperties: false
responses:
'200':
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/jump' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/ramp-schedules/{id}/actions/complete:
post:
operationId: completeRampSchedule
summary: Complete a ramp schedule immediately
description: 'Applies end actions and marks the schedule as `completed`, regardless of
how many steps remain.
'
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/complete' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/ramp-schedules/{id}/actions/approve-step:
post:
operationId: approveStepRampSchedule
summary: Approve the current pending-approval step
description: 'Approves the current step on a schedule in `pending-approval` status and
advances to the next step. Requires the caller to have feature review
permissions for the associated feature.
'
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/approve-step' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/ramp-schedules/{id}/actions/add-target:
post:
operationId: addTargetRampSchedule
summary: Add a target rule to a ramp schedule
description: 'Attaches an additional feature rule to this ramp schedule. The `ruleId`
must identify a rule that is already published and must not already be
controlled by another schedule. `environment` is accepted for backward
compatibility with pre-v2 ramps but is deprecated and no longer required.
'
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
featureId:
type: string
ruleId:
type: string
environment:
deprecated: true
description: Deprecated pre-v2 disambiguator; ignored on v2 rules where `rule.id` is uniquely sufficient.
type: string
required:
- featureId
- ruleId
additionalProperties: false
responses:
'200':
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/add-target' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/ramp-schedules/{id}/actions/eject-target:
post:
operationId: ejectTargetRampSchedule
summary: Remove a target rule from a ramp schedule
description: 'Detaches a target rule from this ramp schedule. Identify the target either
by its `targetId` or by the `[ruleId, environment]` pair.
If this is the last target on the schedule, the schedule is deleted entirely
and the response contains `deleted: true` instead of `rampSchedule`.
'
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
targetId:
description: Target ID (from the targets array)
type: string
ruleId:
description: Rule ID — use as an alternative to targetId
type: string
environment:
deprecated: true
description: Deprecated pre-v2 disambiguator. Optional when used with ruleId; omit on v2 ramps.
type: string
additionalProperties: false
responses:
'200':
content:
application/json:
schema:
anyOf:
- type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
- type: object
properties:
deleted:
type: boolean
rampScheduleId:
type: string
required:
- deleted
- rampScheduleId
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v1/ramp-schedules/{id}/actions/eject-target' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/ramp-schedules/{id}:
get:
operationId: getRampSchedule
summary: Get a single rampSchedule
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
properties:
rampSchedule:
$ref: '#/components/schemas/RampSchedule'
required:
- rampSchedule
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X GET 'https://api.growthbook.io/api/v1/ramp-schedules/{id}' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
delete:
operationId: deleteRampSchedule
summary: Delete a single rampSchedule
description: 'Permanently deletes a ramp schedule. This does not undo any rule patches that
were already applied by completed steps.
'
tags:
- ramp-schedules
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
properties:
deletedId:
type: string
required:
- deletedId
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X DELETE 'https://api.growthbook.io/api/v1/ramp-schedules/{id}' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
put:
operationId: updateRampSchedule
summary: Update a single rampSchedule
description: 'Updates the name, steps, endActions, startDate, or endCondition of a ramp schedule.
Only allowed when the schedule is in `pending`, `ready`, or `paused` status.
**targetId shorthand**: When
# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/growthbook/refs/heads/main/openapi/growthbook-ramp-schedules-api-openapi.yml