Flags API reference

Flags API · Ramps

post/v1/workspaces/{workspace_id}/settings/{setting_id}/values/{environment_id}/rampsAuth

Start 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 · uuid

Id of the setting.

environment_id*string · uuid

Id of an environment of the same project.

workspace_id*string · uuid

Id of the workspace.

Headers

Idempotency-Keystring

Idempotency 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*object

The value to roll out (for a flag, usually `true`). It must differ from the default value.

Example: true

steps*array

1-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.

notestring

A 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 · uuid

Id of the ramp.

workspace_id*string · uuid

The workspace.

project_id*string · uuid

The project.

config_id*string · uuid

The config.

setting_id*string · uuid

The setting.

setting_key*string

The setting's key.

Example: "new_checkout"

environment_id*string · uuid

The environment.

environment_key*string

The environment's key.

Example: "production"

value*object

The value served to the ramped percentage; everyone else keeps the default value.

Example: true

steps*array

The steps and which have been applied.

current_percentage*integer

Percentage served now (0 before the first step).

Example: 25

status*object

State.

Example: "active"

note*string

Note on every step in the history.

Example: "Ramp the new checkout"

change_request_id*string · uuid

The approved change request that started it.

created_by*object

Who started it.

last_change_id*string · uuid

The history entry of the last step.

last_error*object

Why it failed.

created_at*string · date-time

When it was created.

updated_at*string · date-time

When 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)"
}

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"
}