Create a ramp schedule

Creates a new ramp schedule, optionally attaching it to a published feature rule.

Target attachment (optional)

Provide featureId, ruleId, and environment together to attach the schedule to a specific rule on creation. The rule must already be live (published). Each [ruleId, environment] pair can only be controlled by one schedule at a time.

When all three 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.).

If 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, ruleId, and environment to be set (so targetId can be injected).

Requires an Enterprise plan.

POST /ramp-schedules

cURL

With target (simple)

curl -X POST https://api.growthbook.io/api/v1/ramp-schedules \
  -d '{
    "name": "Coverage ramp",
    "featureId": "my-feature",
    "ruleId": "rule_abc",
    "environment": "production",
    "steps": [
      { "trigger": { "type": "interval", "seconds": 86400 }, "actions": [{ "patch": { "coverage": 0.5 } }] },
      { "trigger": { "type": "approval" }, "actions": [{ "patch": { "coverage": 1.0 } }] }
    ]
  }' \
  -u secret_abc123DEF456:

200

{
  "rampSchedule": {
    "id": "<string>",
    "organization": "<string>",
    "dateCreated": "2023-11-07T05:31:56Z",
    "dateUpdated": "2023-11-07T05:31:56Z",
    "name": "<string>",
    "entityType": "feature",
    "entityId": "<string>",
    "targets": [
      {
        "id": "<string>",
        "entityType": "feature",
        "entityId": "<string>",
        "status": "pending-join",
        "ruleId": "<string>",
        "environment": "<string>",
        "activatingRevisionVersion": 123
      }
    ],
    "steps": [
      {
        "trigger": {
          "type": "interval",
          "seconds": 123,
          "at": "2023-11-07T05:31:56Z"
        },
        "actions": [
          {
            "targetType": "feature-rule",
            "targetId": "<string>",
            "patch": {
              "ruleId": "<string>",
              "coverage": 0.5,
              "condition": "<string>",
              "force": "<unknown>"
            }
          }
        ],
        "approvalNotes": "<string>"
      }
    ],
    "status": "pending",
    "currentStepIndex": 0,
    "nextStepAt": "2023-11-07T05:31:56Z",
    "endActions": [
      {
        "targetType": "feature-rule",
        "targetId": "<string>",
        "patch": {
          "ruleId": "<string>",
          "coverage": 0.5,
          "condition": "<string>",
          "force": "<unknown>"
        }
      }
    ],
    "startDate": "2023-11-07T05:31:56Z",
    "endCondition": {
      "trigger": {
        "type": "scheduled",
        "at": "2023-11-07T05:31:56Z"
      }
    },
    "startedAt": "2023-11-07T05:31:56Z",
    "phaseStartedAt": "2023-11-07T05:31:56Z",
    "pausedAt": "2023-11-07T05:31:56Z",
    "elapsedMs": 123
  }
}

Authorizations

bearerAuthbasicAuth

Authorization · string · header · required

If using Bearer auth, pass the Secret Key as the token:

curl https://api.growthbook.io/api/v1 \
  -H "Authorization: Bearer secret_abc123DEF456"

Body

application/json

name · string · required

featureId · string

Feature that anchors this schedule. Required when ruleId/environment are set.

ruleId · string

Rule to attach as the initial target. Requires featureId and environment.

environment · string

Environment of the target rule. Requires featureId and ruleId.

templateId · string

Load steps and endActions from a saved template (featureId+ruleId+environment must also be set for auto-injection)

steps · object[]

Ordered ramp steps. When featureId+ruleId+environment are provided, targetId and patch.ruleId in actions are auto-injected — only supply the patch fields you want to change.

Show child attributes

endActions · object[]

Actions applied when the ramp completes. targetId and patch.ruleId are auto-injected when featureId+ruleId+environment are provided.

Show child attributes

startDate · string<date-time> | null

When to start. Absent/null = immediately on start action.

endCondition · object

Optional hard deadline

Show child attributes

Response

200 - application/json

Success

rampSchedule · object · required

Show child attributes