Flags API reference

Flags API · Settings

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

Replace a value

Replaces the value and the whole targeting (rules, flag-level split, split attribute) in one environment. 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.

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"

value*object

Served when no rule and no split decides. 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: false

rulesarray

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

percentagesarray

Flag-level split after the rules; null or omitted for none.

percentage_attributestring

The user attribute splits hash (1-256 characters, returned exactly as sent); null or omitted for `identifier`.

Example: null

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

PUT 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": false,
  "rules": [
    {}
  ],
  "percentages": [
    {
      "percentage": 10,
      "value": true
    }
  ],
  "percentage_attribute": null
}

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