/v1/workspaces/{workspace_id}/segments/{segment_id}AuthUpdate 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 · uuidId of the segment.
workspace_id*string · uuidId of the workspace.
Request body
keystringNew 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"
namestringDisplay name, 1-200 characters.
descriptionstringFree-text description, at most 1000 characters.
conditionsarrayReplaces 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_editsarrayInstead 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"]}]
versionintegerThe `version` you read; when sent, a mismatch answers 409 `VERSION_CONFLICT`.
Example: 1
notestringA 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 · uuidThe segment's id.
workspace_id*string · uuidThe workspace that owns it.
project_id*string · uuidThe project; a segment can be used by any config of it.
key*stringUnique in the project, case-sensitive; SDKs see it in the config JSON.
Example: "qa_staff"
name*stringDisplay name.
Example: "QA staff"
description*stringFree-text description (may be empty).
Example: ""
seed*stringThe key at creation. It never changes, and confidential values are hashed with it, so renaming the segment keeps them valid.
Example: "qa_staff"
conditions*array1-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*integerIncrements on every change; send it with an update to detect concurrent edits.
Example: 1
usage_count*integerHow many settings use the segment in at least one environment.
Example: 2
created_by*stringWho created it (user or API key id).
created_at*string · date-timeWhen it was created.
updated_at*string · date-timeWhen it last changed.
used_by*arrayEvery (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"
}
]
}