unleash.unleash/website/docs/api/admin/segments.mdx

---
title: /api/admin/segments
---
import ApiRequest from '@site/src/components/ApiRequest'
export const basePath = "api/admin/segments"
export const path = (p) => `${basePath}/${p}`

:::info Availability
Segments are an **experimental feature** available to some Unleash Pro and Unleash Enterprise users. [Get in touch](https://slack.unleash.run) if you'd like to help us develop this feature.
:::

:::note
To use the admin API, you'll need to [create and use an admin API token](../../user_guide/token.md).
:::

The segments API lets you create, read, update, and delete [segments](../../reference/segments.mdx).

## Get all segments

Retrieve all segments that exist in this Unleash instance. Returns a list of [segment objects](#isegment).

<ApiRequest verb="Get" url={basePath} title="Retrieve all existing segments."/>

<details>

<summary>Example responses</summary>

### 200 OK

``` json
[
  {
    "id": 1,
    "name": "my-segment",
    "description": "a segment description",
    "constraints": [],
    "createdBy": "user@example.com",
    "createdAt": "2022-04-01T14:02:25.491Z"
  }
]
```

</details>

## Create segment

Create a new segment with the specified configuration.

<ApiRequest verb="post" url={basePath} title="Create a new segment."
payload={{
  "name": "my-segment",
  "description": "a segment description",
  "constraints": []
}}
/>


<details>

<summary>Example responses</summary>

### 201 Created

The segment was successfully created. This response has no body.

### 400 Bad Request

A segment with the provided name already exists.

</details>

### Payload structure

Use a JSON object with the following properties to create a new segment.

| Property      | Type                                       | Required | Description                      | Example value                                    |
|---------------|--------------------------------------------|----------|----------------------------------|--------------------------------------------------|
| `name`        | string                                     | Yes      | The name of the segment.         | `"mobile-users"`                                 |
| `description` | string                                     | No       | A description of the segment.    | `"This segment is for users on mobile devices."` |
| `constraints` | list of [constraint objects](#iconstraint) | Yes      | The constraints in this segment. | `[]`                                             |

## Get segment by ID

Retrieves the segment with the specified ID.
<ApiRequest verb="Get" url={path("<segment-id>")} title="Retrieve the segment with the provided ID."/>

<details>

<summary>Example responses</summary>

### 200 OK

``` json
{
  "id": 1,
  "name": "my-segment",
  "description": "a segment description",
  "constraints": [],
  "createdBy": "user@example.com",
  "createdAt": "2022-04-01T14:02:25.491Z"
}
```

### 404 Not Found

No segment with the provided ID exists.

</details>

## Update an existing segment

Replace the data of the specified segment with the provided payload.


<ApiRequest verb="put" url={path("<segment-id>")} title="Update a segment with new data."
payload={{
  "name": "my-segment",
  "description": "this is a newly provided description.",
  "constraints": []
}}
/>

<details>

<summary>Example responses</summary>

### 204 No Content

The update was successful. This response has no body.

### 404 Not Found

No segment with the provided ID exists.

</details>

## Delete a segment

Delete the request with the specified ID.

<ApiRequest verb="delete" url={path("<segment-id>")} title="Delete a segment." />

<details>

<summary>Example responses</summary>

### 204 No Content

The segment was deleted successfully.

### 404 Not Found

No segment with the provided ID exists.

### 409 Conflict

The segment is being used by at least one strategy and can not be deleted. To delete the segment, first remove it from any strategies that use it.

</details>

## List strategies that use a specific segment

Retrieve all strategies that use the specified segment. Returns a list of [activation strategy objects](#ifeaturestrategy).

<ApiRequest verb="Get" url={path("<segment-id>/strategies")} title="Retrieve all activation strategies that use the specified segment."/>

<details>

<summary>Example responses</summary>

### 200 OK

``` json
[
  {
    "id": "strategy-id",
    "featureName": "my-feature",
    "projectId": "my-project",
    "environment": "development",
    "strategyName": "my strategy",
    "parameters": {},
    "constraints": [],
    "createdAt": "2022-04-01T14:02:25.491Z"
  }
]
```

### 404 Not Found

No segment with the provided id exists.

</details>

## List segments applied to a specific strategy

Retrieve all segments that are applied to the specified strategy. Returns a list of [segment objects](#isegment).

<ApiRequest verb="Get" url={path("strategies/<strategy-id>")} title="Retrieve all segments that are used by the specified strategy."/>

<details>

<summary>Example responses</summary>

### 200 OK

``` json
[
  {
    "id": 1,
    "name": "my-segment",
    "description": "a segment description",
    "constraints": [],
    "createdBy": "user@example.com",
    "createdAt": "2022-04-01T14:02:25.491Z"
  }
]
```

### 404 Not Found

No strategy with the provided id exists.

</details>


## Replace activation strategy segments

Replace the segments applied to the specified activation strategy with the provided segment list.

<ApiRequest verb="post" url={path("strategies")} title="Replace the segments to the specified strategy."
payload={{
  "projectId": "my-project",
  "strategyId": "my-strategy",
  "environmentId": "development",
  "segmentIds": []
}}
/>

### Remove all segments from an activation strategy

To remove all segments from an activation strategy, use this endpoint and provide an empty list of `segmentIds`. For instance, the following payload would remove all segments from the strategy "my-strategy".

``` json
{
  "projectId": "my-project",
  "strategyId": "my-strategy",
  "environmentId": "development",
  "segmentIds": []
}
```

<details>

<summary>Example responses</summary>

### 201 Created

The strategy's list of segments was successfully updated.

### 403 Forbidden

You do not have access to edit this activation strategy.

### 404 Not Found

No strategy with the provided ID exists.

</details>

### Payload structure

Use a JSON object with the following properties to update the list of applied segments.

| Property        | Type                          | Required | Description                                       | Example value   |
|-----------------|-------------------------------|----------|---------------------------------------------------|-----------------|
| `projectId`     | string                        | Yes      | The ID of the feature toggle's project.           | `"my-project"`  |
| `strategyId`    | string                        | Yes      | The ID of the strategy.                           | `"my-strategy"` |
| `environmentId` | string                        | Yes      | The ID of the environment.                        | `"development"` |
| `segmentIds`    | list of segment IDs (numbers) | Yes      | The list of segment IDs to apply to the strategy. | `[]`            |

## Types

### `ISegment`: segment interface {#isegment}

``` ts
export interface ISegment {
    id: number;
    name: string;
    description?: string;
    constraints: IConstraint[];
    createdBy?: string;
    createdAt: Date;
}
```

### `IConstraint`: constraint interface {#iconstraint}

```ts
export interface IConstraint {
    contextName: string;
    operator: string;
    values?: string[];
    value?: string;
    inverted?: boolean;
    caseInsensitive?: boolean;
}
```

### `IFeatureStrategy`: strategy interface {#ifeaturestrategy}

``` ts
export interface IFeatureStrategy {
    id: string;
    featureName: string;
    projectId: string;
    environment: string;
    strategyName: string;
    parameters: object;
    sortOrder?: number;
    constraints: IConstraint[];
    createdAt?: Date;
}
```