---
title: "Creates a user segment in the resolved project."
method: POST
path: "/api/v1/orgs/{org}/projects/{project}/segments"
tags: ["User Segments"]
---

# Creates a user segment in the resolved project.

`POST /api/v1/orgs/{org}/projects/{project}/segments`

## Request

- Base URL: `https://api.featureflip.io`
- URL: `https://api.featureflip.io/api/v1/orgs/{org}/projects/{project}/segments`
- Auth: API key in header `Authorization`

Requires at least Member. Re-fetches via
ListUserSegmentsQuery (there is no single-segment query) and locates the new
segment by the id returned from CreateUserSegmentCommand so the response
reflects exactly what was persisted (e.g. server-assigned condition ids, folded into the
public shape via FromDto).

## Path parameters

- `org` string, required
- `project` string, required

## Request body

- PublicCreateSegmentRequest: Request body for `POST /api/v1/orgs/{org}/projects/{project}/segments`. Named distinctly from the dashboard's own `CreateUserSegmentRequest` — see PublicCreateEnvironmentRequest for the schemaId-collision rationale (both controllers share one Swagger document).
  - `key` string, nullable, required
  - `name` string, nullable, required
  - `description` string, nullable
  - `conditions` PublicSegmentConditionDto[], nullable, required
    - `attribute` string, nullable, required
    - `operator` 'Equals' | 'NotEquals' | 'Contains' | 'NotContains' | 'GreaterThan' | 'LessThan' | 'GreaterThanOrEqual' | 'LessThanOrEqual' | 'In' | 'NotIn' | 'MatchesRegex' | 'StartsWith' | 'EndsWith' | 'Before' | 'After' | 'SemverEquals' | 'SemverGreaterThan' | 'SemverGreaterThanOrEqual' | 'SemverLessThan' | 'SemverLessThanOrEqual', nullable, required: Allowed values: Equals, NotEquals, Contains, NotContains, GreaterThan, LessThan, GreaterThanOrEqual, LessThanOrEqual, In, NotIn, MatchesRegex, StartsWith, EndsWith, Before, After, SemverEquals, SemverGreaterThan, SemverGreaterThanOrEqual, SemverLessThan, SemverLessThanOrEqual.
    - `values` string[], nullable, required
    - `negate` boolean

## Response `201`

Created

- PublicSegmentResponse: Public representation of a user segment, returned by `GET .../segments`, `GET .../segments/{segment}`, and the body of a successful create.
  - `id` string, uuid, required
  - `key` string, nullable, required
  - `name` string, nullable, required
  - `description` string, nullable
  - `conditions` PublicSegmentConditionDto[], nullable, required
    - `attribute` string, nullable, required
    - `operator` 'Equals' | 'NotEquals' | 'Contains' | 'NotContains' | 'GreaterThan' | 'LessThan' | 'GreaterThanOrEqual' | 'LessThanOrEqual' | 'In' | 'NotIn' | 'MatchesRegex' | 'StartsWith' | 'EndsWith' | 'Before' | 'After' | 'SemverEquals' | 'SemverGreaterThan' | 'SemverGreaterThanOrEqual' | 'SemverLessThan' | 'SemverLessThanOrEqual', nullable, required: Allowed values: Equals, NotEquals, Contains, NotContains, GreaterThan, LessThan, GreaterThanOrEqual, LessThanOrEqual, In, NotIn, MatchesRegex, StartsWith, EndsWith, Before, After, SemverEquals, SemverGreaterThan, SemverGreaterThanOrEqual, SemverLessThan, SemverLessThanOrEqual.
    - `values` string[], nullable, required
    - `negate` boolean
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required
  - `_actions` object: Capability hints: which operations the authenticated caller may perform on this resource, each with allowed + optional reason. Computed from the caller's role and the resource's state. Injected at runtime; safe to ignore. Present only on top-level resource responses — nested occurrences (e.g. a rule inside a targeting-config response) do not carry it.

## Other responses

- `400`: The request is malformed, or it carries an If-Match header, which this endpoint can't evaluate. Send no If-Match, or `*`.
- `401`: Authentication is required, or the supplied API token is invalid or expired.
- `403`: Forbidden
- `404`: Not Found
- `429`: Rate limit exceeded. Retry after the interval indicated by the Retry-After header.

---

[API](https://skmtc.dev/featureflip/apis/management-api.md) · [All operations](https://skmtc.dev/featureflip/apis/management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/featureflip/apis/management-api/revisions/8a77e8581a45?raw)