Start, pause, resume, advance, or abort a rollout ramp
manage_rollout_rampStart, pause, resume, advance, or abort step-by-step percentage rollout ramps on a feature flag targeting rule, applying each audited step to SDKs in one environment.
Instructions
Manage a rollout ramp on a flag in one environment. A ramp raises a percentage rollout step by step: it applies the first step at once, then each next step when the previous hold runs out. Every step is an audited rule change that reaches SDKs over the stream. action=start needs rule + steps: rule is a targeting rule id (from get_targeting) whose rule serves a percentage rollout, or "default" for the default rule. Steps (1 to 20) must rise, the first not below the rule's current rollout. A default-rule ramp may name the variation to ramp to (variation id; needed when the default rule has no rollout yet) and bucketBy, and on reaching 100% makes that variation the default. The flag must be on in the environment. action=pause keeps the rest of the hold; action=resume continues from the rule as it stands now; action=advance applies the next step now and needs expectedStepIndex (the currentStepIndex you last saw); action=abort stops the ramp and leaves the rule at percent (0-100, at or below the current one). pause, resume, advance and abort need ramp and accept ifMatch. Editing the rule by hand or turning the flag off pauses a ramp. Starting needs the Team plan or above; every write needs a Member token.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"action": "<action>",
"project": "<project>",
"flag": "<flag>",
"environment": "<environment>"
},
"name": "manage_rollout_ramp"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| flag | Yes | Flag key or id | |
| ramp | No | Ramp id (see list_rollout_ramps); required for every action but start | |
| rule | No | start only: the targeting rule id (see get_targeting), or "default" for the default rule | |
| steps | No | start only: the ladder, in rising order | |
| action | Yes | start needs rule + steps; the others need ramp | |
| reason | No | Why you are making this change. Recorded in the audit log, and required when the environment (or, for project-wide changes, any environment in the project) is marked critical. | |
| ifMatch | No | etag from list_rollout_ramps with ramp. The write is refused with 412 if the resource changed since that read; re-read and re-apply. Omit to write unconditionally. | |
| percent | No | abort only (required): the rollout percentage to leave the rule at | |
| project | Yes | Project key | |
| bucketBy | No | start on rule="default" only: the context attribute to bucket by (default: key) | |
| variation | No | start on rule="default" only: the variation id to ramp to (see get_flag) | |
| environment | Yes | Environment key, e.g. production | |
| freeze_override | No | Owner/Admin only: break an active change freeze for this one change. Requires `reason`. Use it only after a change_frozen error says can_override is true. | |
| idempotency_key | No | Idempotency-Key header for start | |
| expectedStepIndex | No | advance only (required): the currentStepIndex you last saw; a ramp that moved on is refused (409) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| etag | No | ETag of what this write left behind. Pass it as ifMatch on the next update to chain writes without re-reading. Absent when the API sent none; read the resource again before the next conditional write. | |
| steps | No | ||
| ruleId | No | ||
| status | No | ||
| abortedAt | No | ||
| createdAt | No | ||
| nextStepAt | No | ||
| completedAt | No | ||
| pausedDetail | No | ||
| pausedReason | No | ||
| isDefaultRule | No | ||
| startedByName | No | ||
| currentStepIndex | No | ||
| targetVariationId | No |