Flags API reference

Flags API · Settings

post/v1/workspaces/{workspace_id}/configs/{config_id}/settingsAuth

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

Id of the config.

workspace_id*string · uuid

Id of the workspace.

Headers

Idempotency-Keystring

Idempotency 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*string

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

namestring

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

descriptionstring

Free-text description, at most 1000 characters.

hintstring

Short hint, at most 500 characters.

tagsarray

Tags, at most 20, each 1-50 characters.

Example: ["checkout"]

lifecycleobject

Defaults to `temporary`.

owner_idstring · uuid

A workspace member who owns the flag. Checked against the workspace members (422 `OWNER_NOT_A_MEMBER`).

initial_valueobject

The 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

ordinalinteger

Sort position. Defaults to after the last one.

Example: 0

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 · 201 The new setting with its values.

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

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