| 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 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. :::
The segments API lets you create, read, update, and delete segments.
Retrieve all segments that exist in this Unleash instance. Returns a list of segment objects.
Example responses
[
{
"id": 1,
"name": "my-segment",
"description": "a segment description",
"constraints": [],
"createdBy": "user@example.com",
"createdAt": "2022-04-01T14:02:25.491Z"
}
]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": [] }} />
Example responses
The segment was successfully created. This response has no body.
A segment with the provided name already exists.
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 | Yes | The constraints in this segment. | [] |
Retrieves the segment with the specified ID. <ApiRequest verb="Get" url={path("")} title="Retrieve the segment with the provided ID."/>
Example responses
{
"id": 1,
"name": "my-segment",
"description": "a segment description",
"constraints": [],
"createdBy": "user@example.com",
"createdAt": "2022-04-01T14:02:25.491Z"
}No segment with the provided ID exists.
Replace the data of the specified segment with the provided payload.
<ApiRequest verb="put" url={path("")} title="Update a segment with new data." payload={{ "name": "my-segment", "description": "this is a newly provided description.", "constraints": [] }} />
Example responses
The update was successful. This response has no body.
No segment with the provided ID exists.
Delete the request with the specified ID.
<ApiRequest verb="delete" url={path("")} title="Delete a segment." />
Example responses
The segment was deleted successfully.
No segment with the provided ID exists.
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.
Retrieve all strategies that use the specified segment. Returns a list of activation strategy objects.
<ApiRequest verb="Get" url={path("/strategies")} title="Retrieve all activation strategies that use the specified segment."/>
Example responses
[
{
"id": "strategy-id",
"featureName": "my-feature",
"projectId": "my-project",
"environment": "development",
"strategyName": "my strategy",
"parameters": {},
"constraints": [],
"createdAt": "2022-04-01T14:02:25.491Z"
}
]No segment with the provided id exists.
Retrieve all segments that are applied to the specified strategy. Returns a list of segment objects.
<ApiRequest verb="Get" url={path("strategies/")} title="Retrieve all segments that are used by the specified strategy."/>
Example responses
[
{
"id": 1,
"name": "my-segment",
"description": "a segment description",
"constraints": [],
"createdBy": "user@example.com",
"createdAt": "2022-04-01T14:02:25.491Z"
}
]No strategy with the provided id exists.
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": [] }} />
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".
{
"projectId": "my-project",
"strategyId": "my-strategy",
"environmentId": "development",
"segmentIds": []
}Example responses
The strategy's list of segments was successfully updated.
You do not have access to edit this activation strategy.
No strategy with the provided ID exists.
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. | [] |
export interface ISegment {
id: number;
name: string;
description?: string;
constraints: IConstraint[];
createdBy?: string;
createdAt: Date;
}export interface IConstraint {
contextName: string;
operator: string;
values?: string[];
value?: string;
inverted?: boolean;
caseInsensitive?: boolean;
}export interface IFeatureStrategy {
id: string;
featureName: string;
projectId: string;
environment: string;
strategyName: string;
parameters: object;
sortOrder?: number;
constraints: IConstraint[];
createdAt?: Date;
}