---
title: "Create a segment"
method: POST
path: "/segments"
tags: ["Segments"]
---

# Create a segment

`POST /segments`

Creates a new segment. Returns 201 with the created segment and Location header.

## Headers

- `Idempotency-Key` string

## Request body

- V4SegmentCreate
  - `name` string, required — Segment name (max 256 characters).
  - `conditions` V4SegmentCondition[] — Targeting rules. Every rule must match (logical AND). Optional; omit to create a segment with no rules.
    - `metric` string, required — Metric identifier. Corresponds to a configured `SegmentMetric` (`ref_table_field`). Common values: `environment`, `client_uid`, `custom_uid`, `client_advertiser_id`, `renewable`, `target_platform`.
    - `comparator` string, required — Comparison operator applied between the metric and `value`. `contains` / `not_contains` map to SQL LIKE semantics on string metrics; numeric comparators (`gt`/`gte`/`lt`/`lte`) require a numeric metric.
    - `value` string, required — String-encoded value to compare against. Cast to the metric's underlying type (e.g. int, string) on the server.
    - `negate` boolean — If `true`, the rule matches when the comparison is false (logical NOT applied to the individual rule). Defaults to `false`.

## Response `201`

Segment created

- V4Segment
  - `object` string, required
  - `id` string, required — Segment identifier.
  - `url` string, required — Canonical API path.
  - `name` string, required — Display name.
  - `is_system` boolean, required — Whether this is a predefined system segment (read-only).
  - `conditions` V4SegmentCondition[], required — Targeting rules. Every rule must match for a user to fall into the segment (logical AND). Omit on update to leave existing conditions untouched; pass an empty array to clear.
    - `metric` string, required — Metric identifier. Corresponds to a configured `SegmentMetric` (`ref_table_field`). Common values: `environment`, `client_uid`, `custom_uid`, `client_advertiser_id`, `renewable`, `target_platform`.
    - `comparator` string, required — Comparison operator applied between the metric and `value`. `contains` / `not_contains` map to SQL LIKE semantics on string metrics; numeric comparators (`gt`/`gte`/`lt`/`lte`) require a numeric metric.
    - `value` string, required — String-encoded value to compare against. Cast to the metric's underlying type (e.g. int, string) on the server.
    - `negate` boolean — If `true`, the rule matches when the comparison is false (logical NOT applied to the individual rule). Defaults to `false`.
  - `created_at` string, date-time, required — ISO 8601 creation timestamp.
  - `updated_at` string, date-time, required — ISO 8601 last update timestamp.

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `409` — Segment already exists
- `415` — Unsupported Content-Type
- `422` — Unprocessable entity
- `500` — Internal error
- `504` — Upstream timeout

---

[API](https://skmtc.net/qonversion/apis/qonversion-rest-api-v4.md) · [All operations](https://skmtc.net/qonversion/apis/qonversion-rest-api-v4/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/qonversion/qonversion-rest-api-v4/revisions/e3f72cf8951c/schema)