> ## Documentation Index > Fetch the complete documentation index at: https://documentation.qonversion.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a segment > Creates a new segment. Returns 201 with the created segment and Location header. ## OpenAPI ````yaml /api-reference/rest-api-v4.yaml post /segments openapi: 3.0.3 info: title: Qonversion REST API v4 version: '4.0' description: >- Qonversion REST API v4 follows REST standards. It has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. servers: - url: https://api.qonversion.io/v4 description: Production security: - secretAuth: [] tags: - name: Users description: Retrieve Qonversion users - name: User Properties description: Manage user-level attributes - name: Identities description: Link Qonversion users to your own auth IDs - name: Entitlements description: Entitlement definitions and user grants - name: Purchases description: A user's purchase history - name: Products description: Products configured in the Qonversion dashboard - name: Customers description: Aggregated customer records, properties, permissions, and metrics - name: Segments description: Dynamic and system segments of users - name: Experiments description: Paywall and offering A/B experiments - name: Screens description: No-code paywall screens — CRUD, publish, analytics - name: Analytics description: Charts, cards, cohorts, LTV, and insights - name: Exports description: Asynchronous data exports - name: Events description: Event catalog - name: Scheduled Reports description: Recurring reports delivered to external destinations - name: Integrations description: Third-party integrations configuration - name: Automations description: Event-driven automations - name: Project Settings description: Project-level configuration, secret, and store credentials paths: /segments: post: tags: - Segments summary: Create a segment description: >- Creates a new segment. Returns 201 with the created segment and Location header. operationId: v4CreateSegment parameters: - name: Idempotency-Key in: header required: false schema: type: string description: Idempotency key for safe retries. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/V4SegmentCreate' responses: '201': description: Segment created headers: Location: description: URL of the created segment schema: type: string example: /v4/segments/premium-users content: application/json: schema: $ref: '#/components/schemas/V4Segment' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/V4Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/V4Error' '409': description: Segment already exists content: application/json: schema: $ref: '#/components/schemas/V4Error' '415': description: Unsupported Content-Type content: application/json: schema: $ref: '#/components/schemas/V4Error' '422': description: Unprocessable entity content: application/json: schema: $ref: '#/components/schemas/V4Error' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/V4Error' '504': description: Upstream timeout content: application/json: schema: $ref: '#/components/schemas/V4Error' security: - secretAuth: [] components: schemas: V4SegmentCreate: type: object required: - name properties: name: type: string description: Segment name (max 256 characters). example: Premium Users conditions: type: array description: | Targeting rules. Every rule must match (logical AND). Optional; omit to create a segment with no rules. items: $ref: '#/components/schemas/V4SegmentCondition' example: - metric: environment comparator: eq value: prod negate: false V4Segment: type: object required: - object - id - url - name - is_system - conditions - created_at - updated_at properties: object: type: string example: segment id: type: string description: Segment identifier. example: premium-users url: type: string description: Canonical API path. example: /v4/segments/premium-users name: type: string description: Display name. example: Premium Users is_system: type: boolean description: Whether this is a predefined system segment (read-only). conditions: type: array description: > 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. items: $ref: '#/components/schemas/V4SegmentCondition' created_at: type: string format: date-time description: ISO 8601 creation timestamp. example: '2025-09-15T12:30:00Z' updated_at: type: string format: date-time description: ISO 8601 last update timestamp. example: '2025-11-03T10:26:40Z' V4Error: type: object required: - error properties: error: type: object required: - type - code - message properties: type: type: string enum: - request - resource - logical - internal code: type: string description: | Machine-readable snake_case error code. Examples include `invalid_data`, `invalid_request`, `invalid_product_id`, `not_found`, `already_exists`, `offering_already_exists`, `product_not_in_project`, `cannot_set_main_directly`, `cannot_demote_main`, `cannot_patch_experiment_variant`, `cannot_delete_experiment_variant`, and `cannot_setmain_experiment_variant`. Resource-specific codes are documented on the corresponding reference page. message: type: string description: Human-readable description. May change; do not parse. details: type: array nullable: true description: Per-field validation errors, present on 400 validation failures. items: type: object properties: field: type: string message: type: string V4SegmentCondition: type: object description: | A single targeting rule. Rules are joined with logical AND within a segment. required: - metric - comparator - value properties: metric: type: string description: | Metric identifier. Corresponds to a configured `SegmentMetric` (`ref_table_field`). Common values: `environment`, `client_uid`, `custom_uid`, `client_advertiser_id`, `renewable`, `target_platform`. example: environment comparator: type: string x-extensible-enum: - eq - ne - gt - gte - lt - lte - contains - not_contains description: | 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. example: eq value: type: string description: | String-encoded value to compare against. Cast to the metric's underlying type (e.g. int, string) on the server. example: prod negate: type: boolean description: | If `true`, the rule matches when the comparison is false (logical NOT applied to the individual rule). Defaults to `false`. default: false securitySchemes: secretAuth: type: http scheme: bearer bearerFormat: sk_… description: >- Bearer authentication using the project **Secret Key** (prefixed with `sk_`, or `test_sk_` for sandbox). All v4 public endpoints require the Secret Key — see [Authentication](/reference/v4/authentication). Never expose the Secret Key in client-side code. ````