/v1/workspaces/{workspace_id}/settings/{setting_id}/values/{environment_id}/change-requestsAuthPropose a change
Proposes a value write (`replace` or `patch`, as PUT / PATCH …/values take them) or a timed ramp (`ramp`) for review instead of making it. The proposal is validated as the write would be and stored without any confidential cleartext; the environment's owners and admins are emailed and `change_request.created` is sent to webhooks. Works in any environment; where the environment's `approval_policy` applies to the caller it is the only way to change a value. Send the `version` you read.
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
operation*enum (3)`replace`: a new value and the whole targeting (`value`, `rules`, `percentages`, `percentage_attribute`, as PUT …/values). `patch`: the quick edits (`value`, `percentage_attribute`, `clear_rules`, `rule_edits`, as PATCH …/values). `ramp`: a timed percentage rollout of `value` over `steps`, started when the request is applied.
Example: "patch"
version*integerThe `version` of the value you read; the proposal is made against it.
Example: 7
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)"
valueobject`replace`: the default value. `patch`: the new plain value (the toggle). `ramp`: the value the ramp serves to its growing percentage.
Example: true
rulesarray`replace` only: the targeting rules, as PUT …/values takes them.
percentagesarray`replace` only: the flag-level split, or null.
percentage_attributestring`replace` / `patch`: the attribute splits hash; null for `identifier`.
clear_rulesboolean`patch` only: drop every rule and split so `value` is served to everyone.
Example: false
rule_editsarray`patch` only: add or remove values in list conditions of the existing rules.
stepsarray`ramp` only: 1-20 steps, strictly increasing in time and percentage, all in the future (within a year).
Response · 201 The pending change request.
id*string · uuidId of the change request.
workspace_id*string · uuidThe workspace.
project_id*string · uuidThe project.
config_id*string · uuidThe config.
setting_id*string · uuidThe setting the change is for.
setting_key*stringThe setting's key.
Example: "new_checkout"
environment_id*string · uuidThe environment the change is for.
environment_key*stringThe environment's key.
Example: "production"
kind*object`value`: a new value and targeting. `ramp`: a timed percentage rollout, started when applied.
Example: "value"
status*object`pending` until it has `required_approvals` approvals (`approved`); `scheduled` when an approved request waits for its `run_at`; `applied`; `rejected` by a reviewer; `cancelled` by its author or a reviewer; `failed` when a scheduled apply found the value changed (rebase it).
Example: "pending"
base_version*integerThe value's `version` the proposal was made against.
Example: 7
current_version*integerThe value's `version` now.
Example: 7
stale*booleanTrue when the value changed since the proposal (`current_version` ≠ `base_version`) while the request is still open: rebase or recreate it before applying.
Example: false
before*objectWhat the environment served when the change was proposed: `value`, `rules`, `percentages`, `percentage_attribute`. Confidential lists show as counts.
after*objectWhat it will serve once applied (same shape), or for a `ramp` the ramp `{value, steps}`.
diff*arrayJSON Patch (RFC 6902) from `before` to `after`.
summary*arrayThe change in words ("value false → true", "rule 2 percentage 10 → 25").
Example: ["value false → true"]
note*stringThe author's note.
Example: "Turn on for everyone"
required_approvals*integerApprovals needed (from the environment when it was proposed).
Example: 1
approvals*integerApprovals so far.
Example: 0
reviews*arrayEvery decision, oldest first.
author*objectWho proposed it (and for whom, when an agent did).
applied_change_id*string · uuidThe history entry the apply wrote.
applied_at*string · date-timeWhen it was applied.
scheduled_change_id*string · uuidThe scheduled change that will apply it.
last_error*objectWhy the last scheduled apply failed.
created_at*string · date-timeWhen it was proposed.
updated_at*string · date-timeWhen it last changed state.
Example
Request
POST https://api.flags.productcraft.co/v1/workspaces/{workspace_id}/settings/{setting_id}/values/{environment_id}/change-requests
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"operation": "patch",
"version": 7,
"note": "Roll out the new checkout to everyone (FLAG-142)",
"value": true,
"rules": [
{}
],
"percentages": [
{}
],
"percentage_attribute": "string",
"clear_rules": false,
"rule_edits": [
{
"condition_index": 0,
"values_add": [
"qa-bot@example.com"
],
"values_remove": [
"old-bot@example.com"
],
"rule_index": 0
}
],
"steps": [
{
"percentage": 25,
"at": "2026-11-20T09:00:00.000Z"
}
]
}import { Flags } from "@productcraft/flags";
// Reads PRODUCTCRAFT_API_KEY from the environment
const flags = new Flags();
const changeRequest = await flags.settings.values.changeRequests.create("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { operation: "patch", version: 7 });flags.settings.values.changeRequests.create(settingId, environmentId, params, options?): Flags.ChangeRequest
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",
"kind": "value",
"status": "pending",
"base_version": 7,
"current_version": 7,
"stale": false,
"before": {},
"after": {},
"diff": [
{
"op": {},
"path": "/rules/1/percentages/0/percentage",
"value": 25
}
],
"summary": [
"value false → true"
],
"note": "Turn on for everyone",
"required_approvals": 1,
"approvals": 0,
"reviews": [
{
"reviewer_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
"reviewer_label": "ada@example.com",
"decision": "approved",
"note": "Looks good",
"created_at": "2026-01-01T00:00:00.000Z"
}
],
"author": {},
"applied_change_id": "00000000-0000-0000-0000-000000000000",
"applied_at": "2026-01-01T00:00:00.000Z",
"scheduled_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"
}