/v1/workspaces/{workspace_id}/settings/{setting_id}/values/{environment_id}/rampsAuthStart a ramp
Rolls `value` out to a growing percentage at set times (for example 5% → 25% → 50% → 100%): each step sets the flag-level split, so users already in keep the value as it grows (sticky bucketing), and a final 100% step makes it the default. Rules still decide first. Where the environment needs approval for the caller this answers 409 `APPROVAL_REQUIRED`: propose it as a change request with `operation: ramp`.
Path parameters
setting_id*string · uuidId of the setting.
environment_id*string · uuidId of an environment of the same project.
workspace_id*string · uuidId of the workspace.
Headers
Idempotency-KeystringIdempotency key (1-256 characters, `[A-Za-z0-9._:-]`). A retry with the same key and body returns the first response for 24 h.
Request body
value*objectThe value to roll out (for a flag, usually `true`). It must differ from the default value.
Example: true
steps*array1-20 steps, strictly increasing in time and percentage, all in the future (within a year). End at 100 to finish with the value served to everyone.
notestringA note for reviewers and the history (at most 500 characters). Required where the environment has `require_note`.
Example: "Roll out the new checkout to everyone (FLAG-142)"
Response · 201 The active ramp.
id*string · uuidId of the ramp.
workspace_id*string · uuidThe workspace.
project_id*string · uuidThe project.
config_id*string · uuidThe config.
setting_id*string · uuidThe setting.
setting_key*stringThe setting's key.
Example: "new_checkout"
environment_id*string · uuidThe environment.
environment_key*stringThe environment's key.
Example: "production"
value*objectThe value served to the ramped percentage; everyone else keeps the default value.
Example: true
steps*arrayThe steps and which have been applied.
current_percentage*integerPercentage served now (0 before the first step).
Example: 25
status*objectState.
Example: "active"
note*stringNote on every step in the history.
Example: "Ramp the new checkout"
change_request_id*string · uuidThe approved change request that started it.
created_by*objectWho started it.
last_change_id*string · uuidThe history entry of the last step.
last_error*objectWhy it failed.
created_at*string · date-timeWhen it was created.
updated_at*string · date-timeWhen it last changed.
Example
Request
POST https://api.flags.productcraft.co/v1/workspaces/{workspace_id}/settings/{setting_id}/values/{environment_id}/ramps
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"value": true,
"steps": [
{
"percentage": 25,
"at": "2026-11-20T09:00:00.000Z"
}
],
"note": "Roll out the new checkout to everyone (FLAG-142)"
}import { Flags } from "@productcraft/flags";
// Reads PRODUCTCRAFT_API_KEY from the environment
const flags = new Flags();
const ramp = await flags.settings.values.ramps.create("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { steps: [{ at: "2026-11-20T09:00:00.000Z", percentage: 25 }], value: true });flags.settings.values.ramps.create(settingId, environmentId, params, options?): Flags.Ramp
Response
{
"id": "00000000-0000-0000-0000-000000000000",
"workspace_id": "00000000-0000-0000-0000-000000000000",
"project_id": "00000000-0000-0000-0000-000000000000",
"config_id": "00000000-0000-0000-0000-000000000000",
"setting_id": "00000000-0000-0000-0000-000000000000",
"setting_key": "new_checkout",
"environment_id": "00000000-0000-0000-0000-000000000000",
"environment_key": "production",
"value": true,
"steps": [
{
"percentage": 25,
"at": "2026-01-01T00:00:00.000Z",
"applied": false
}
],
"current_percentage": 25,
"status": "active",
"note": "Ramp the new checkout",
"change_request_id": "00000000-0000-0000-0000-000000000000",
"created_by": {},
"last_change_id": "00000000-0000-0000-0000-000000000000",
"last_error": {},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}