/v1/workspaces/{workspace_id}/settings/{setting_id}AuthUpdate a setting
Key, name, description, hint, tags, lifecycle, owner or order; only the fields you send change. The type cannot change. Renaming the key keeps the seed (users stay in their split buckets) and needs `flags.protected.update` when the project has a protected environment.
Path parameters
setting_id*string · uuidId of the setting.
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. SDK code reading the old key gets its default, so check `dependents` and your code first. Needs `flags.protected.update` when the project has a protected environment. The seed does not change.
Example: "new_checkout_v2"
namestringDisplay name, 1-200 characters.
descriptionstringFree-text description, at most 1000 characters.
hintstringShort hint, at most 500 characters.
tagsarrayReplaces the tags: at most 20, each 1-50 characters.
lifecycleobject`temporary` or `permanent`.
owner_idstring · uuidA workspace member, or null to clear.
ordinalintegerSort position.
typeobjectCannot change: sending a type other than the current one answers 422 `SETTING_TYPE_IMMUTABLE`.
notestringA change note (at most 500 characters), saved on the history entry. Environments with `require_note` refuse value writes without one.
Example: "Ticket FLAG-142"
Response · 200 The updated setting.
id*string · uuidThe setting's id.
workspace_id*string · uuidThe workspace that owns it.
project_id*string · uuidThe project.
config_id*string · uuidThe config it belongs to.
key*stringThe key SDKs read it by; unique in the config, case-sensitive.
Example: "new_checkout"
name*stringDisplay name.
Example: "New checkout"
description*stringFree-text description (may be empty).
Example: ""
hint*stringA short hint shown next to the flag in the console (may be empty).
Example: ""
type*object`boolean` is a feature flag; the others are typed settings. Cannot change.
Example: "boolean"
tags*arrayFree-form tags.
Example: ["checkout"]
lifecycle*object`temporary` (a release flag you plan to remove) or `permanent` (an ops switch or a setting).
Example: "temporary"
owner_id*string · uuidThe platform user who owns the flag (a workspace member), or null.
seed*stringThe value percentage splits hash with: the key at creation (or the ConfigCat key on import). It never changes, so renaming a key does not move users between variations.
Example: "new_checkout"
ordinal*integerSort position in the config (ascending).
Example: 0
created_by*stringWho created it (user or API key id).
created_at*string · date-timeWhen it was created.
updated_at*string · date-timeWhen its metadata last changed.
values*arrayIts value and targeting in every environment, in environment order.
dependents*objectWhat depends on this setting: check before deleting or renaming it.
Example
Request
PATCH https://api.flags.productcraft.co/v1/workspaces/{workspace_id}/settings/{setting_id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"key": "new_checkout_v2",
"name": "string",
"description": "string",
"hint": "string",
"tags": [
"string"
],
"lifecycle": {},
"owner_id": "00000000-0000-0000-0000-000000000000",
"ordinal": 0,
"type": {},
"note": "Ticket FLAG-142"
}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",
"key": "new_checkout",
"name": "New checkout",
"description": "",
"hint": "",
"type": "boolean",
"tags": [
"checkout"
],
"lifecycle": "temporary",
"owner_id": "00000000-0000-0000-0000-000000000000",
"seed": "new_checkout",
"ordinal": 0,
"created_by": "string",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"values": [
{
"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"
}
],
"dependents": {}
}