Flags API reference

Flags API · Settings

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

Update 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 · uuid

Id of the setting.

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

namestring

Display name, 1-200 characters.

descriptionstring

Free-text description, at most 1000 characters.

hintstring

Short hint, at most 500 characters.

tagsarray

Replaces the tags: at most 20, each 1-50 characters.

lifecycleobject

`temporary` or `permanent`.

owner_idstring · uuid

A workspace member, or null to clear.

ordinalinteger

Sort position.

typeobject

Cannot change: sending a type other than the current one answers 422 `SETTING_TYPE_IMMUTABLE`.

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"

Response · 200 The updated setting.

id*string · uuid

The setting's id.

workspace_id*string · uuid

The workspace that owns it.

project_id*string · uuid

The project.

config_id*string · uuid

The config it belongs to.

key*string

The key SDKs read it by; unique in the config, case-sensitive.

Example: "new_checkout"

name*string

Display name.

Example: "New checkout"

description*string

Free-text description (may be empty).

Example: ""

hint*string

A 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*array

Free-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 · uuid

The platform user who owns the flag (a workspace member), or null.

seed*string

The 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*integer

Sort position in the config (ascending).

Example: 0

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 its metadata last changed.

values*array

Its value and targeting in every environment, in environment order.

dependents*object

What 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": {}
}