Starts a ramp on the default (fallthrough) rule.
const url = 'https://api.featureflip.io/api/v1/orgs/example/projects/example/flags/example/environments/example/default-rule/ramp';const options = { method: 'POST', headers: {Authorization: '<Authorization>', 'Content-Type': 'application/json'}, body: '{"steps":[{"percent":1,"holdMinutes":1}],"variationId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","bucketBy":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.featureflip.io/api/v1/orgs/example/projects/example/flags/example/environments/example/default-rule/ramp \ --header 'Authorization: <Authorization>' \ --header 'Content-Type: application/json' \ --data '{ "steps": [ { "percent": 1, "holdMinutes": 1 } ], "variationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "bucketBy": "example" }'A ladder ending at 100% finalises: the variation becomes
the default variation and the rollout is cleared. Requires at least Member. As with a rule ramp, a replayed
201 carries no ETag: GET the ramp for its current one.
Authorizations
Section titled “ Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “ Path Parameters ”Header Parameters
Section titled “ Header Parameters ”Why you are making this change, recorded in the audit log. Percent-encoded UTF-8 (encode it the way encodeURIComponent does); at most 2048 characters after decoding. Required when the target environment — or, for project-wide changes, any environment in the project — requires a change reason; without one the request is refused with 422 change_reason_required.
Owner/Admin only: true breaks an active change freeze for this one request; requires X-Intent-Reason.
Request Body
Section titled “ Request Body ”Request body for POST …/default-rule/ramp. VariationId (and optionally
BucketBy) set the rollout up when the default rule has none; with one configured they may be
omitted, or must match it. A ladder ending at 100% finalises: the variation becomes the default variation.
object
One rung of a rollout ramp: the percentage served, then how long it holds before the next rung. Both fields are required.
object
Example generated
{ "steps": [ { "percent": 1, "holdMinutes": 1 } ], "variationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "bucketBy": "example"}Request body for POST …/default-rule/ramp. VariationId (and optionally
BucketBy) set the rollout up when the default rule has none; with one configured they may be
omitted, or must match it. A ladder ending at 100% finalises: the variation becomes the default variation.
object
One rung of a rollout ramp: the percentage served, then how long it holds before the next rung. Both fields are required.
object
Example generated
{ "steps": [ { "percent": 1, "holdMinutes": 1 } ], "variationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "bucketBy": "example"}Request body for POST …/default-rule/ramp. VariationId (and optionally
BucketBy) set the rollout up when the default rule has none; with one configured they may be
omitted, or must match it. A ladder ending at 100% finalises: the variation becomes the default variation.
object
One rung of a rollout ramp: the percentage served, then how long it holds before the next rung. Both fields are required.
object
Example generated
{ "steps": [ { "percent": 1, "holdMinutes": 1 } ], "variationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "bucketBy": "example"}Responses
Section titled “ Responses ”Created
A rollout ramp (#4653, #5180) as /api/v1 returns it. Flag and environment are implicit in the route.
A ramp drives either a targeting rule (RuleId set) or the default rule
(IsDefaultRule true, TargetVariationId the variation it rolls out).
Status is Running, Paused, Completed or Aborted.
CurrentStepIndex is the step last applied, -1 before the first. NextStepAt is
set only while running and not yet on the last step.
object
One rung of a rollout ramp: the percentage served, then how long it holds before the next rung. Both fields are required.
object
Example generated
{ "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "ruleId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "isDefaultRule": true, "targetVariationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "status": "example", "steps": [ { "percent": 1, "holdMinutes": 1 } ], "currentStepIndex": 1, "nextStepAt": "2026-04-15T12:00:00Z", "pausedReason": "example", "pausedDetail": "example", "startedByName": "example", "createdAt": "2026-04-15T12:00:00Z", "completedAt": "2026-04-15T12:00:00Z", "abortedAt": "2026-04-15T12:00:00Z"}Headers
Section titled “ Headers ”The maximum number of requests permitted per rate-limit window for this caller.
The number of requests remaining in the current rate-limit window.
The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.
The request is malformed, or it carries an If-Match header, which this endpoint can’t evaluate. Send no If-Match, or *.
The frozen public-API error contract. error codes are stable snake_case strings. Wire keys
are frozen snake_case too (error, message, docs_url, fields,
retry_after) — the global camelCase naming policy would otherwise emit
docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName
always wins over the policy, so these are pinned explicitly rather than relying on the
property names already being lowercase for the single-word ones.
did_you_mean, next_actions and connection_id are ADDITIVE optional keys
(null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so
pre-existing error bodies are byte-for-byte unchanged when they’re absent.
connection_id is present only on the sso_required error: the organization
requires single sign-on, and this credential didn’t come through its identity provider.
connection_id identifies which SSO connection to sign in with.
plan_limit is present only on the plan_limit_reached error: which plan cap the
request would have exceeded, so a client can branch on it without parsing message.
change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the
write, so a client can show when it ends and whether the caller may break it, without parsing message.
object
object
object
The cap behind a plan_limit_reached error. resource is the capped collection
(projects, environments, flags, webhooks, members);
plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is
the cap. The environment and flag caps are per project.
object
The freeze behind a change_frozen error: id and name of the window, the environment’s
environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may
break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).
object
Example
{ "error": "not_found", "message": "Flag 'new-checkout-flw' was not found in project 'checkout'.", "docs_url": "https://featureflip.io/docs/management-api/errors/not_found", "did_you_mean": [ "new-checkout-flow" ], "next_actions": [ { "method": "GET", "path": "/api/v1/orgs/acme/projects/checkout/flags" } ]}Headers
Section titled “ Headers ”The maximum number of requests permitted per rate-limit window for this caller.
The number of requests remaining in the current rate-limit window.
The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.
Authentication is required, or the supplied API token is invalid or expired.
The frozen public-API error contract. error codes are stable snake_case strings. Wire keys
are frozen snake_case too (error, message, docs_url, fields,
retry_after) — the global camelCase naming policy would otherwise emit
docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName
always wins over the policy, so these are pinned explicitly rather than relying on the
property names already being lowercase for the single-word ones.
did_you_mean, next_actions and connection_id are ADDITIVE optional keys
(null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so
pre-existing error bodies are byte-for-byte unchanged when they’re absent.
connection_id is present only on the sso_required error: the organization
requires single sign-on, and this credential didn’t come through its identity provider.
connection_id identifies which SSO connection to sign in with.
plan_limit is present only on the plan_limit_reached error: which plan cap the
request would have exceeded, so a client can branch on it without parsing message.
change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the
write, so a client can show when it ends and whether the caller may break it, without parsing message.
object
object
object
The cap behind a plan_limit_reached error. resource is the capped collection
(projects, environments, flags, webhooks, members);
plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is
the cap. The environment and flag caps are per project.
object
The freeze behind a change_frozen error: id and name of the window, the environment’s
environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may
break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).
object
Example
{ "error": "not_found", "message": "Flag 'new-checkout-flw' was not found in project 'checkout'.", "docs_url": "https://featureflip.io/docs/management-api/errors/not_found", "did_you_mean": [ "new-checkout-flow" ], "next_actions": [ { "method": "GET", "path": "/api/v1/orgs/acme/projects/checkout/flags" } ]}Headers
Section titled “ Headers ”The maximum number of requests permitted per rate-limit window for this caller.
The number of requests remaining in the current rate-limit window.
The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.
Forbidden
The frozen public-API error contract. error codes are stable snake_case strings. Wire keys
are frozen snake_case too (error, message, docs_url, fields,
retry_after) — the global camelCase naming policy would otherwise emit
docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName
always wins over the policy, so these are pinned explicitly rather than relying on the
property names already being lowercase for the single-word ones.
did_you_mean, next_actions and connection_id are ADDITIVE optional keys
(null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so
pre-existing error bodies are byte-for-byte unchanged when they’re absent.
connection_id is present only on the sso_required error: the organization
requires single sign-on, and this credential didn’t come through its identity provider.
connection_id identifies which SSO connection to sign in with.
plan_limit is present only on the plan_limit_reached error: which plan cap the
request would have exceeded, so a client can branch on it without parsing message.
change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the
write, so a client can show when it ends and whether the caller may break it, without parsing message.
object
object
object
The cap behind a plan_limit_reached error. resource is the capped collection
(projects, environments, flags, webhooks, members);
plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is
the cap. The environment and flag caps are per project.
object
The freeze behind a change_frozen error: id and name of the window, the environment’s
environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may
break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).
object
Example
{ "error": "not_found", "message": "Flag 'new-checkout-flw' was not found in project 'checkout'.", "docs_url": "https://featureflip.io/docs/management-api/errors/not_found", "did_you_mean": [ "new-checkout-flow" ], "next_actions": [ { "method": "GET", "path": "/api/v1/orgs/acme/projects/checkout/flags" } ]}Headers
Section titled “ Headers ”The maximum number of requests permitted per rate-limit window for this caller.
The number of requests remaining in the current rate-limit window.
The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.
Not Found
The frozen public-API error contract. error codes are stable snake_case strings. Wire keys
are frozen snake_case too (error, message, docs_url, fields,
retry_after) — the global camelCase naming policy would otherwise emit
docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName
always wins over the policy, so these are pinned explicitly rather than relying on the
property names already being lowercase for the single-word ones.
did_you_mean, next_actions and connection_id are ADDITIVE optional keys
(null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so
pre-existing error bodies are byte-for-byte unchanged when they’re absent.
connection_id is present only on the sso_required error: the organization
requires single sign-on, and this credential didn’t come through its identity provider.
connection_id identifies which SSO connection to sign in with.
plan_limit is present only on the plan_limit_reached error: which plan cap the
request would have exceeded, so a client can branch on it without parsing message.
change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the
write, so a client can show when it ends and whether the caller may break it, without parsing message.
object
object
object
The cap behind a plan_limit_reached error. resource is the capped collection
(projects, environments, flags, webhooks, members);
plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is
the cap. The environment and flag caps are per project.
object
The freeze behind a change_frozen error: id and name of the window, the environment’s
environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may
break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).
object
Example
{ "error": "not_found", "message": "Flag 'new-checkout-flw' was not found in project 'checkout'.", "docs_url": "https://featureflip.io/docs/management-api/errors/not_found", "did_you_mean": [ "new-checkout-flow" ], "next_actions": [ { "method": "GET", "path": "/api/v1/orgs/acme/projects/checkout/flags" } ]}Headers
Section titled “ Headers ”The maximum number of requests permitted per rate-limit window for this caller.
The number of requests remaining in the current rate-limit window.
The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.
Conflict
The frozen public-API error contract. error codes are stable snake_case strings. Wire keys
are frozen snake_case too (error, message, docs_url, fields,
retry_after) — the global camelCase naming policy would otherwise emit
docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName
always wins over the policy, so these are pinned explicitly rather than relying on the
property names already being lowercase for the single-word ones.
did_you_mean, next_actions and connection_id are ADDITIVE optional keys
(null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so
pre-existing error bodies are byte-for-byte unchanged when they’re absent.
connection_id is present only on the sso_required error: the organization
requires single sign-on, and this credential didn’t come through its identity provider.
connection_id identifies which SSO connection to sign in with.
plan_limit is present only on the plan_limit_reached error: which plan cap the
request would have exceeded, so a client can branch on it without parsing message.
change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the
write, so a client can show when it ends and whether the caller may break it, without parsing message.
object
object
object
The cap behind a plan_limit_reached error. resource is the capped collection
(projects, environments, flags, webhooks, members);
plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is
the cap. The environment and flag caps are per project.
object
The freeze behind a change_frozen error: id and name of the window, the environment’s
environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may
break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).
object
Example
{ "error": "not_found", "message": "Flag 'new-checkout-flw' was not found in project 'checkout'.", "docs_url": "https://featureflip.io/docs/management-api/errors/not_found", "did_you_mean": [ "new-checkout-flow" ], "next_actions": [ { "method": "GET", "path": "/api/v1/orgs/acme/projects/checkout/flags" } ]}Headers
Section titled “ Headers ”The maximum number of requests permitted per rate-limit window for this caller.
The number of requests remaining in the current rate-limit window.
The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.
A change reason is required: this change affects an environment that requires one (error code change_reason_required). Retry with the X-Intent-Reason header.
The frozen public-API error contract. error codes are stable snake_case strings. Wire keys
are frozen snake_case too (error, message, docs_url, fields,
retry_after) — the global camelCase naming policy would otherwise emit
docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName
always wins over the policy, so these are pinned explicitly rather than relying on the
property names already being lowercase for the single-word ones.
did_you_mean, next_actions and connection_id are ADDITIVE optional keys
(null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so
pre-existing error bodies are byte-for-byte unchanged when they’re absent.
connection_id is present only on the sso_required error: the organization
requires single sign-on, and this credential didn’t come through its identity provider.
connection_id identifies which SSO connection to sign in with.
plan_limit is present only on the plan_limit_reached error: which plan cap the
request would have exceeded, so a client can branch on it without parsing message.
change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the
write, so a client can show when it ends and whether the caller may break it, without parsing message.
object
object
object
The cap behind a plan_limit_reached error. resource is the capped collection
(projects, environments, flags, webhooks, members);
plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is
the cap. The environment and flag caps are per project.
object
The freeze behind a change_frozen error: id and name of the window, the environment’s
environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may
break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).
object
Example
{ "error": "not_found", "message": "Flag 'new-checkout-flw' was not found in project 'checkout'.", "docs_url": "https://featureflip.io/docs/management-api/errors/not_found", "did_you_mean": [ "new-checkout-flow" ], "next_actions": [ { "method": "GET", "path": "/api/v1/orgs/acme/projects/checkout/flags" } ]}Headers
Section titled “ Headers ”The maximum number of requests permitted per rate-limit window for this caller.
The number of requests remaining in the current rate-limit window.
The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.
A change freeze covers this environment (error code change_frozen; the change_freeze object names the window, when it ends and whether the caller may break it). An Owner or Admin can retry with X-Freeze-Override: true and an X-Intent-Reason.
The frozen public-API error contract. error codes are stable snake_case strings. Wire keys
are frozen snake_case too (error, message, docs_url, fields,
retry_after) — the global camelCase naming policy would otherwise emit
docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName
always wins over the policy, so these are pinned explicitly rather than relying on the
property names already being lowercase for the single-word ones.
did_you_mean, next_actions and connection_id are ADDITIVE optional keys
(null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so
pre-existing error bodies are byte-for-byte unchanged when they’re absent.
connection_id is present only on the sso_required error: the organization
requires single sign-on, and this credential didn’t come through its identity provider.
connection_id identifies which SSO connection to sign in with.
plan_limit is present only on the plan_limit_reached error: which plan cap the
request would have exceeded, so a client can branch on it without parsing message.
change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the
write, so a client can show when it ends and whether the caller may break it, without parsing message.
object
object
object
The cap behind a plan_limit_reached error. resource is the capped collection
(projects, environments, flags, webhooks, members);
plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is
the cap. The environment and flag caps are per project.
object
The freeze behind a change_frozen error: id and name of the window, the environment’s
environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may
break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).
object
Example
{ "error": "not_found", "message": "Flag 'new-checkout-flw' was not found in project 'checkout'.", "docs_url": "https://featureflip.io/docs/management-api/errors/not_found", "did_you_mean": [ "new-checkout-flow" ], "next_actions": [ { "method": "GET", "path": "/api/v1/orgs/acme/projects/checkout/flags" } ]}Headers
Section titled “ Headers ”The maximum number of requests permitted per rate-limit window for this caller.
The number of requests remaining in the current rate-limit window.
The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.
Rate limit exceeded. Retry after the interval indicated by the Retry-After header.
The frozen public-API error contract. error codes are stable snake_case strings. Wire keys
are frozen snake_case too (error, message, docs_url, fields,
retry_after) — the global camelCase naming policy would otherwise emit
docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName
always wins over the policy, so these are pinned explicitly rather than relying on the
property names already being lowercase for the single-word ones.
did_you_mean, next_actions and connection_id are ADDITIVE optional keys
(null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so
pre-existing error bodies are byte-for-byte unchanged when they’re absent.
connection_id is present only on the sso_required error: the organization
requires single sign-on, and this credential didn’t come through its identity provider.
connection_id identifies which SSO connection to sign in with.
plan_limit is present only on the plan_limit_reached error: which plan cap the
request would have exceeded, so a client can branch on it without parsing message.
change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the
write, so a client can show when it ends and whether the caller may break it, without parsing message.
object
object
object
The cap behind a plan_limit_reached error. resource is the capped collection
(projects, environments, flags, webhooks, members);
plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is
the cap. The environment and flag caps are per project.
object
The freeze behind a change_frozen error: id and name of the window, the environment’s
environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may
break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).
object
Example
{ "error": "not_found", "message": "Flag 'new-checkout-flw' was not found in project 'checkout'.", "docs_url": "https://featureflip.io/docs/management-api/errors/not_found", "did_you_mean": [ "new-checkout-flow" ], "next_actions": [ { "method": "GET", "path": "/api/v1/orgs/acme/projects/checkout/flags" } ]}Headers
Section titled “ Headers ”Number of seconds to wait before retrying the request.
The maximum number of requests permitted per rate-limit window for this caller.
The number of requests remaining in the current rate-limit window.
The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.