Flags API reference

Flags API · Change-Requests

post/v1/workspaces/{workspace_id}/settings/{setting_id}/values/{environment_id}/change-requestsAuth

Propose 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 · 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

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*integer

The `version` of the value you read; the proposal is made against it.

Example: 7

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

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

Id of the change request.

workspace_id*string · uuid

The workspace.

project_id*string · uuid

The project.

config_id*string · uuid

The config.

setting_id*string · uuid

The setting the change is for.

setting_key*string

The setting's key.

Example: "new_checkout"

environment_id*string · uuid

The environment the change is for.

environment_key*string

The 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*integer

The value's `version` the proposal was made against.

Example: 7

current_version*integer

The value's `version` now.

Example: 7

stale*boolean

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

What the environment served when the change was proposed: `value`, `rules`, `percentages`, `percentage_attribute`. Confidential lists show as counts.

after*object

What it will serve once applied (same shape), or for a `ramp` the ramp `{value, steps}`.

diff*array

JSON Patch (RFC 6902) from `before` to `after`.

summary*array

The change in words ("value false → true", "rule 2 percentage 10 → 25").

Example: ["value false → true"]

note*string

The author's note.

Example: "Turn on for everyone"

required_approvals*integer

Approvals needed (from the environment when it was proposed).

Example: 1

approvals*integer

Approvals so far.

Example: 0

reviews*array

Every decision, oldest first.

author*object

Who proposed it (and for whom, when an agent did).

applied_change_id*string · uuid

The history entry the apply wrote.

applied_at*string · date-time

When it was applied.

scheduled_change_id*string · uuid

The scheduled change that will apply it.

last_error*object

Why the last scheduled apply failed.

created_at*string · date-time

When it was proposed.

updated_at*string · date-time

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

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