Flags API reference

Flags API · Segments

post/v1/workspaces/{workspace_id}/projects/{project_id}/segmentsAuth

Create a segment

A reusable set of ANDed user conditions that any config of the project can target with `{segment: {segment_id, comparator: in | not_in}}`. Confidential lists are stored as hashes plus encrypted cleartext; the response shows only their count.

Path parameters

project_id*string · uuid

Id of the project.

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

Unique in the project; must start with a letter and contain only letters, digits, "_", "." and "-", at most 128 characters. Becomes the segment's permanent seed.

Example: "qa_staff"

namestring

Display name, 1-200 characters. Defaults to the key.

Example: "QA staff"

descriptionstring

Free-text description, at most 1000 characters.

conditions*array

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.

Example: [{"user":{"attribute":"email","comparator":"ends_with_any_hashed","values":["@acme.test"]}}]

notestring

A 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 · 201 The new segment.

id*string · uuid

The segment's id.

workspace_id*string · uuid

The workspace that owns it.

project_id*string · uuid

The project; a segment can be used by any config of it.

key*string

Unique in the project, case-sensitive; SDKs see it in the config JSON.

Example: "qa_staff"

name*string

Display name.

Example: "QA staff"

description*string

Free-text description (may be empty).

Example: ""

seed*string

The key at creation. It never changes, and confidential values are hashed with it, so renaming the segment keeps them valid.

Example: "qa_staff"

conditions*array

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. Confidential lists are shown as `{hashed: true, count, list_id, editable}`.

version*integer

Increments on every change; send it with an update to detect concurrent edits.

Example: 1

usage_count*integer

How many settings use the segment in at least one environment.

Example: 2

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 it last changed.

used_by*array

Every (setting, environment) whose rules use the segment. A segment listed anywhere cannot be deleted.

Example

Request

POST https://api.flags.productcraft.co/v1/workspaces/{workspace_id}/projects/{project_id}/segments
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "key": "qa_staff",
  "name": "QA staff",
  "description": "string",
  "conditions": [
    {
      "user": {
        "attribute": "email",
        "comparator": "ends_with_any_hashed",
        "values": [
          "@acme.test"
        ]
      }
    }
  ],
  "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"
    }
  ]
}