Flags API reference

Flags API · Settings

patch/v1/workspaces/{workspace_id}/settings/{setting_id}/values/{environment_id}Auth

Update a value

The quick edits: `value` (the toggle), `percentage_attribute`, `rule_edits` to add or remove values in a list condition of an existing rule (a tester, a QA account) without re-sending the other rules, and `clear_rules: true` to drop every rule and split so `value` is served to everyone (the kill switch). Send the `version` you read. A protected environment needs `flags.protected.update`; one change and one revision per request, none when nothing changed.

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.

Request body

version*integer

The `version` you read; 409 `VERSION_CONFLICT` when it moved.

Example: 3

notestring

A change note (at most 500 characters), saved on the history entry. Environments with `require_note` refuse value writes without one.

Example: "Ticket FLAG-142"

valueobject

The new plain value (the on/off toggle for a flag). Must match the setting type: `boolean` true/false; `string` a string; `integer` a safe integer; `number` a finite number; `json` a string holding JSON text (for example `"{\"limit\":5}"`). At most 100 KB. Strings are stored and returned byte for byte.

Example: true

percentage_attributestring

The attribute splits hash; null for `identifier`.

clear_rulesboolean

Remove every rule and the flag-level split, so `value` is served to everyone (the kill switch). Restore the targeting from the history if needed.

Example: false

rule_editsarray

Add or remove values in list conditions of the existing rules without re-sending the targeting: each edit names a rule and a condition by index (as `GET` returns them, so send the `version` you read) and changes only that condition's values, with set semantics. A 422 `INVALID_TARGETING` names an index with no rule or condition, or a condition that is not a list. Re-adding a present value or removing an absent one is not a change: the current value comes back with the same `version` and no history entry. Cannot be combined with `clear_rules`.

Example: [{"rule_index":0,"condition_index":0,"values_add":["qa-bot@example.com"]}]

Response · 200 The new value.

setting_id*string · uuid

The setting.

environment_id*string · uuid

The environment.

environment_key*string

The environment's key.

Example: "production"

value*object

Served when no rule and no split decides (and to everyone when there are none).

Example: false

rules*array

Targeting rules, first match wins (at most 50). Each rule has `conditions` and exactly one of `serve` (a value) or `percentages` (a split).

percentages*array

Flag-level split after the rules (null for none).

percentage_attribute*string

The user attribute the splits hash; null means `identifier`.

Example: null

version*integer

Send it back with the next write; a stale one answers 409 `VERSION_CONFLICT`.

Example: 3

updated_by*object

Who wrote the value last.

updated_at*string · date-time

When the value last changed.

Example

Request

PATCH https://api.flags.productcraft.co/v1/workspaces/{workspace_id}/settings/{setting_id}/values/{environment_id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "version": 3,
  "note": "Ticket FLAG-142",
  "value": true,
  "percentage_attribute": "string",
  "clear_rules": false,
  "rule_edits": [
    {
      "rule_index": 0,
      "condition_index": 0,
      "values_add": [
        "qa-bot@example.com"
      ]
    }
  ]
}

Response

{
  "setting_id": "00000000-0000-0000-0000-000000000000",
  "environment_id": "00000000-0000-0000-0000-000000000000",
  "environment_key": "production",
  "value": false,
  "rules": [
    {}
  ],
  "percentages": [
    {
      "percentage": 10,
      "value": true
    }
  ],
  "percentage_attribute": null,
  "version": 3,
  "updated_by": {},
  "updated_at": "2026-01-01T00:00:00.000Z"
}