/v1/workspaces/{workspace_id}/configs/{config_id}/settingsAuthCreate a setting
Adds a feature flag (`boolean`) or a typed setting to the config, with a value in every environment (`initial_value`, else the type's zero). Needs `flags.create`; a non-zero `initial_value` is also a value write in every environment (protected ones need `flags.protected.update`).
Path parameters
config_id*string · uuidId of the config.
workspace_id*string · uuidId of the workspace.
Headers
Idempotency-KeystringIdempotency key (1-256 characters, `[A-Za-z0-9._:-]`). A retry with the same key and body returns the first response for 24 h.
Request body
key*stringThe key SDKs read it by, unique in the config; must start with a letter and contain only letters, digits, "_", "." and "-", at most 128 characters.
Example: "new_checkout"
namestringDisplay name, 1-200 characters. Defaults to the key.
Example: "New checkout"
type*object`boolean` for a feature flag; `string`, `integer`, `number` or `json` for a setting. Cannot change later.
Example: "boolean"
descriptionstringFree-text description, at most 1000 characters.
hintstringShort hint, at most 500 characters.
tagsarrayTags, at most 20, each 1-50 characters.
Example: ["checkout"]
lifecycleobjectDefaults to `temporary`.
owner_idstring · uuidA workspace member who owns the flag. Checked against the workspace members (422 `OWNER_NOT_A_MEMBER`).
initial_valueobjectThe value in every environment. Defaults to the type's zero: `false`, `""`, `0`, `0`, `"{}"`. A non-zero value in a protected environment needs `flags.protected.update`. 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
ordinalintegerSort position. Defaults to after the last one.
Example: 0
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 · 201 The new setting with its values.
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
POST https://api.flags.productcraft.co/v1/workspaces/{workspace_id}/configs/{config_id}/settings
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"key": "new_checkout",
"name": "New checkout",
"type": "boolean",
"description": "string",
"hint": "string",
"tags": [
"checkout"
],
"lifecycle": {},
"owner_id": "00000000-0000-0000-0000-000000000000",
"initial_value": false,
"ordinal": 0,
"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": {}
}