Flags API reference

Flags API · Segments

patch/v1/workspaces/{workspace_id}/segments/{segment_id}Auth

Update a segment

Key, name, description or conditions; only the fields you send change. To add or remove values in one list condition without re-sending the others, send `condition_edits` (with the `version` you read). Edit a confidential list with `list_id` plus `values_add` / `values_remove`, or with `condition_edits`. A segment used in a protected environment also needs `flags.protected.update` there.

Path parameters

segment_id*string · uuid

Id of the segment.

workspace_id*string · uuid

Id of the workspace.

Request body

keystring

New key; must start with a letter and contain only letters, digits, "_", "." and "-", at most 128 characters. The seed does not change, so confidential hashes stay valid.

Example: "qa_team"

namestring

Display name, 1-200 characters.

descriptionstring

Free-text description, at most 1000 characters.

conditionsarray

Replaces the conditions. 1-20 conditions, ANDed in order; each is `{user: {attribute, comparator, values}}` (segments hold user conditions only). Confidential comparators take cleartext `values` (stored hashed with the segment's seed and the project salt, and encrypted at rest), `values_hashed`, or `list_id` with `values_add` / `values_remove` to edit a stored list. To keep a confidential list, send its `list_id` (or echo the `{hashed: true, list_id, …}` object as `values`).

Example: [{"user":{"attribute":"email","comparator":"ends_with_any_hashed","list_id":"3f0c6a3e-0f5e-4b8e-9d1a-2c7b9f1e8a10","values_add":["@beta.test"]}}]

condition_editsarray

Instead of `conditions`: add or remove values in list conditions without re-sending the others. Each edit names a condition by index and changes only its values, with set semantics (`values_remove` first). A 422 `INVALID_TARGETING` names an index with no condition, or a condition that is not a list. Re-adding a present value or removing an absent one is not a change (same `version`, no history entry). Send `version` so an edit against a stale read is refused.

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

versioninteger

The `version` you read; when sent, a mismatch answers 409 `VERSION_CONFLICT`.

Example: 1

notestring

A change note (at most 500 characters), saved on the history entry. A segment used in an environment with `require_note` cannot change without one.

Example: "Add the beta testers domain"

Response · 200 The updated segment.

id*string · uuid

The segment's id.

workspace_id*string · uuid

The workspace that owns it.

project_id*string · uuid

The project; a segment can be used by any config of it.

key*string

Unique in the project, case-sensitive; SDKs see it in the config JSON.

Example: "qa_staff"

name*string

Display name.

Example: "QA staff"

description*string

Free-text description (may be empty).

Example: ""

seed*string

The key at creation. It never changes, and confidential values are hashed with it, so renaming the segment keeps them valid.

Example: "qa_staff"

conditions*array

1-20 conditions, ANDed in order; each is `{user: {attribute, comparator, values}}` (segments hold user conditions only). Confidential comparators take cleartext `values` (stored hashed with the segment's seed and the project salt, and encrypted at rest), `values_hashed`, or `list_id` with `values_add` / `values_remove` to edit a stored list. Confidential lists are shown as `{hashed: true, count, list_id, editable}`.

version*integer

Increments on every change; send it with an update to detect concurrent edits.

Example: 1

usage_count*integer

How many settings use the segment in at least one environment.

Example: 2

created_by*string

Who created it (user or API key id).

created_at*string · date-time

When it was created.

updated_at*string · date-time

When it last changed.

used_by*array

Every (setting, environment) whose rules use the segment. A segment listed anywhere cannot be deleted.

Example

Request

PATCH https://api.flags.productcraft.co/v1/workspaces/{workspace_id}/segments/{segment_id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "key": "qa_team",
  "name": "string",
  "description": "string",
  "conditions": [
    {
      "user": {
        "attribute": "email",
        "comparator": "ends_with_any_hashed",
        "list_id": "3f0c6a3e-0f5e-4b8e-9d1a-2c7b9f1e8a10",
        "values_add": [
          "@beta.test"
        ]
      }
    }
  ],
  "condition_edits": [
    {
      "condition_index": 0,
      "values_add": [
        "qa-bot@example.com"
      ]
    }
  ],
  "version": 1,
  "note": "Add the beta testers domain"
}

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "00000000-0000-0000-0000-000000000000",
  "project_id": "00000000-0000-0000-0000-000000000000",
  "key": "qa_staff",
  "name": "QA staff",
  "description": "",
  "seed": "qa_staff",
  "conditions": [
    {
      "user": {}
    }
  ],
  "version": 1,
  "usage_count": 2,
  "created_by": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "used_by": [
    {
      "setting_id": "00000000-0000-0000-0000-000000000000",
      "setting_key": "new_checkout",
      "config_id": "00000000-0000-0000-0000-000000000000",
      "config_key": "main",
      "environment_id": "00000000-0000-0000-0000-000000000000",
      "environment_key": "production"
    }
  ]
}