---
title: "Create a dynamic segment on an asset"
method: POST
path: "/assets/{asset_id}/dynamic-segments"
tags: ["DynamicSegments"]
---

# Create a dynamic segment on an asset

`POST /assets/{asset_id}/dynamic-segments`

## Request

- Base URL: `https://enterprise.knak.io/api/published/v1`
- URL: `https://enterprise.knak.io/api/published/v1/assets/{asset_id}/dynamic-segments`
- Auth: none declared
- TypeScript: <https://skmtc.dev/knak/apis/knak-enterprise-api/docs/assets/:asset_id/dynamic-segments/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a [dynamic segment](#tag/dynamic_segment) scoped to a single asset.
Requires the `local_dynamic_segments` permission. A user who cannot create a local segment in the builder cannot create one through this endpoint.

## Identifying merge tags
A condition names the merge tag it tests by id, not by expression. Obtain ids from [`GET /merge-tags`](#tag/MergeTags). Knak derives the platform expression and returns it as the read-only `category` field.

## Operators
The operators available to a condition depend on its `merge_tag_type`. Four of them take no value at all, and sending one anyway is rejected.

| `merge_tag_type` | Operators | `value` |
| --- | --- | --- |
| `string` | `equals`, `not-equals`, `contains`, `not-contains`, `in`, `startsWith`, `not-startsWith`, `endsWith`, `not-endsWith`, `length-equals` | Required, max 200 characters |
| `string` | `hasContent`, `not-hasContent` | **Omit** |
| `number` | `equals`, `not-equals`, `greaterThan`, `greaterThanOrEqualTo`, `lessThan`, `lessThanOrEqualTo` | Required |
| `date` | `equals`, `not-equals`, `greaterThan`, `greaterThanOrEqualTo`, `lessThan`, `lessThanOrEqualTo` | Required |
| `relative_date` | `equals`, `not-equals`, `greaterThan`, `greaterThanOrEqualTo`, `lessThan`, `lessThanOrEqualTo` | Required |
| `boolean` | `isTrue`, `isFalse` | **Omit** |

## Limits
- 20 platform segments per request
- Condition sets nest 4 deep
- 20 conditions and 5 nested condition sets per condition set
- 200 characters per string value

## Platform support
Only `marketing_cloud` is supported for segment conditional logic. Sending any other platform returns 422.

## Atomicity
Every platform segment is validated before any is written, so a request that fails on its third entry leaves nothing behind.

## Path parameters

- `asset_id` string, required

## Request body

- object
  - `name` string, required: Must be unique among the segments already on this asset.
  - `platform_dynamic_segments` PlatformDynamicSegmentInput[], required
    - `platform` 'marketing_cloud', required: Only `marketing_cloud` is supported for segment conditional logic. Any other platform is rejected with 422.
    - `integration_id` string, nullable: Id of the [integration](#tag/integration) to bind this platform segment to. Optional. When supplied it must belong to `platform`.
    - `conditional_logic` DynamicSegmentConditionSetInput, required: A group of conditions in a request body, joined by `and` or `or`. Condition sets nest to a maximum depth of 4.
      - `type` 'condition_set', required
      - `conjunction` 'and' | 'or', required: How the entries in `children` combine.
      - `children` union[], required: Conditions and nested condition sets. A single set holds at most 20 conditions and at most 5 nested condition sets.
        - union
          - DynamicSegmentConditionInput: A single condition in a request body. Identifies the merge tag by id; Knak derives the platform expression for you and returns it as `category` on read.
            - `type` 'condition', required
            - `merge_tag_id` string, required: Id of the [merge tag](#tag/merge_tag) this condition tests. Obtain it from `GET /merge-tags`. The tag must belong to your company and to the same platform as the enclosing platform segment.
            - `merge_tag_type` 'string' | 'number' | 'date' | 'relative_date' | 'boolean', required: The value type of the merge tag, which determines the operators available to this condition.
            - `operator` string, required: Must be an operator valid for `merge_tag_type`. See the operator table on the create operation.
            - `value` union: The value to compare against. **Omit this property entirely** for the four operators that take no value: `hasContent` and `not-hasContent` on `string`, `isTrue` and `isFalse` on `boolean`. If you send `value` anyway for one of these four operators, it is ignored rather than rejected, regardless of its shape, including `null` or a string over 200 characters. Required for every other operator, where strings are limited to 200 characters.
              - …
          - DynamicSegmentConditionSetInput (recursive)

## Response `201`

Created

- DynamicSegmentItem
  - `data` DynamicSegment
    - `type` string
    - `id` string
    - `attributes` DynamicSegmentAttributes
      - `id` string
      - `name` string: Unique among the segments on the same asset.
      - `asset_id` string, nullable: The asset this segment belongs to. Null for a global segment, which these endpoints can list but not create, edit, or delete.
      - `is_global` boolean: True when the segment is shared company wide rather than scoped to an asset.
      - `platform_dynamic_segments` PlatformDynamicSegment[]
        - `id` string
        - `platform` string: Not restricted to the platforms accepted on write. Segments authored in the builder for other platforms are returned here, and their `conditional_logic` will have a null `merge_tag_id` on its conditions.
        - `integration_id` string: Id of the [integration](#tag/integration) this platform segment is bound to. **An empty string when no integration is set**, never null.
        - `conditional_logic` DynamicSegmentConjunction: A group of conditions, joined by `and` or `or`.
          - `type` 'condition_set', required
          - `conjunction` 'and' | 'or': How the entries in `children` combine. Absent when the group has no conditions to combine.
          - `children` union[], required: Conditions and nested condition sets.
            - union
              - …

## Other responses

- `400`: Bad Request. The body is the wrong shape: a required property is missing, or a property has the wrong type.
- `401`: Unauthenticated
- `403`: Unauthorized
- `404`: Not Found
- `422`: Unprocessable Entity. The body is well formed but breaks a business rule. `meta.platform_segment_index` identifies which entry failed.

---

[API](https://skmtc.dev/knak/apis/knak-enterprise-api.md) - [All operations](https://skmtc.dev/knak/apis/knak-enterprise-api/llms.txt) - [OpenAPI document](https://skmtc.dev/knak/apis/knak-enterprise-api/revisions/31d2c94edfcc?raw)