/api/admin/segments
Plan: Pro and Enterprise | Version: 4.13+
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.
Get all segments
Retrieve all segments that exist in this Unleash instance. Returns a list of segment objects.
- HTTP
- cURL
- HTTPie
GET <unleash-url>/api/admin/segments
Authorization: <API-token>
content-type: application/json
curl -H "Content-Type: application/json" \
-H "Authorization: <API-token>" \
-X GET \
<unleash-url>/api/admin/segments
http GET \
<unleash-url>/api/admin/segments \
Authorization:<API-token> \
Example responses
200 OK
[
{
"id": 1,
"name": "my-segment",
"description": "a segment description",
"constraints": [],
"createdBy": "user@example.com",
"createdAt": "2022-04-01T14:02:25.491Z"
}
]
Create segment
Create a new segment with the specified configuration.
- HTTP
- cURL
- HTTPie
POST <unleash-url>/api/admin/segments
Authorization: <API-token>
content-type: application/json
{
"name": "my-segment",
"description": "a segment description",
"constraints": []
}
curl -H "Content-Type: application/json" \
-H "Authorization: <API-token>" \
-X POST \
-d '{
"name": "my-segment",
"description": "a segment description",
"constraints": []
}' \
<unleash-url>/api/admin/segments
echo '{
"name": "my-segment",
"description": "a segment description",
"constraints": []
}' \
| http POST \
<unleash-url>/api/admin/segments \
Authorization:<API-token>
Example responses
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 | Yes | The constraints in this segment. | [] |
Get segment by ID
Retrieves the segment with the specified ID.
- HTTP
- cURL
- HTTPie
GET <unleash-url>/api/admin/segments/<segment-id>
Authorization: <API-token>
content-type: application/json
curl -H "Content-Type: application/json" \
-H "Authorization: <API-token>" \
-X GET \
<unleash-url>/api/admin/segments/<segment-id>
http GET \
<unleash-url>/api/admin/segments/<segment-id> \
Authorization:<API-token> \
Example responses
Update an existing segment
Replace the data of the specified segment with the provided payload.
- HTTP
- cURL
- HTTPie
PUT <unleash-url>/api/admin/segments/<segment-id>
Authorization: <API-token>
content-type: application/json
{
"name": "my-segment",
"description": "this is a newly provided description.",
"constraints": []
}
curl -H "Content-Type: application/json" \
-H "Authorization: <API-token>" \
-X PUT \
-d '{
"name": "my-segment",
"description": "this is a newly provided description.",
"constraints": []
}' \
<unleash-url>/api/admin/segments/<segment-id>
echo '{
"name": "my-segment",
"description": "this is a newly provided description.",
"constraints": []
}' \
| http PUT \
<unleash-url>/api/admin/segments/<segment-id> \
Authorization:<API-token>
Example responses
Delete a segment
Delete the request with the specified ID.
- HTTP
- cURL
- HTTPie
DELETE <unleash-url>/api/admin/segments/<segment-id>
Authorization: <API-token>
content-type: application/json
curl -H "Content-Type: application/json" \
-H "Authorization: <API-token>" \
-X DELETE \
<unleash-url>/api/admin/segments/<segment-id>
http DELETE \
<unleash-url>/api/admin/segments/<segment-id> \
Authorization:<API-token> \
Example responses
List strategies that use a specific segment
Retrieve all strategies that use the specified segment. Returns a list of activation strategy objects.
- HTTP
- cURL
- HTTPie
GET <unleash-url>/api/admin/segments/<segment-id>/strategies
Authorization: <API-token>
content-type: application/json
curl -H "Content-Type: application/json" \
-H "Authorization: <API-token>" \
-X GET \
<unleash-url>/api/admin/segments/<segment-id>/strategies
http GET \
<unleash-url>/api/admin/segments/<segment-id>/strategies \
Authorization:<API-token> \
Example responses
List segments applied to a specific strategy
Retrieve all segments that are applied to the specified strategy. Returns a list of segment objects.
- HTTP
- cURL
- HTTPie
GET <unleash-url>/api/admin/segments/strategies/<strategy-id>
Authorization: <API-token>
content-type: application/json
curl -H "Content-Type: application/json" \
-H "Authorization: <API-token>" \
-X GET \
<unleash-url>/api/admin/segments/strategies/<strategy-id>
http GET \
<unleash-url>/api/admin/segments/strategies/<strategy-id> \
Authorization:<API-token> \
Example responses
Replace activation strategy segments
Replace the segments applied to the specified activation strategy with the provided segment list.
- HTTP
- cURL
- HTTPie
POST <unleash-url>/api/admin/segments/strategies
Authorization: <API-token>
content-type: application/json
{
"projectId": "my-project",
"strategyId": "my-strategy",
"environmentId": "development",
"segmentIds": [
61,
62,
63,
64
]
}
curl -H "Content-Type: application/json" \
-H "Authorization: <API-token>" \
-X POST \
-d '{
"projectId": "my-project",
"strategyId": "my-strategy",
"environmentId": "development",
"segmentIds": [
61,
62,
63,
64
]
}' \
<unleash-url>/api/admin/segments/strategies
echo '{
"projectId": "my-project",
"strategyId": "my-strategy",
"environmentId": "development",
"segmentIds": [
61,
62,
63,
64
]
}' \
| http POST \
<unleash-url>/api/admin/segments/strategies \
Authorization:<API-token>
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".
{
"projectId": "my-project",
"strategyId": "my-strategy",
"environmentId": "development",
"segmentIds": []
}
Example responses
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 flag'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. | [] |
API types
This section describes the data objects returned by the endpoints in the segments API. For information on a specific endpoint, refer to its specific description above.
Segment
Example
{
"id": 12054,
"name": "segment name",
"description": "segment description",
"constraints": [],
"createdBy": "you@example.com",
"createdAt": "2022-05-23T15:45:22.000Z"
}
Description
Property | Type | Required | Description | Example value |
---|---|---|---|---|
id | number | Yes | The segment's ID. | 546 |
name | string | Yes | The segment's name | "my-segment" |
description | string | No | An optional description of the segment. | "segment description" |
constraints | list of constraint objects | Yes | The list of constraint objects in the segment. | [] |
createdBy | string | No | An identifier for who created the segment. | "you@example.com" |
createdAt | timestamp string | Yes | The time when the segment was created. Format: YYYY-MM-DDThh:mm:ss.sTZD | "2022-04-23T13:56:24.45+01:00" |
Constraint
Example
{
"contextName": "appName",
"operator": "STR_CONTAINS",
"values": [],
"inverted": false,
"caseInsensitive": false
}
Description
values
and value
Some constraint operators only support single values. If a constraint uses one of these operators, the payload will contain a value
property with the correct value. However, for backwards compatibility reasons, the payload will also contain a values
property. If the operator accepts multiple values, the value
property will not be present. Visit the strategy constraints documentation for more information on what operators support what number of values.
Property | Type | Required | Description | Example value |
---|---|---|---|---|
contextName | string | Yes | The name of the context field targeted by the constraint. | "myContextField" |
operator | string, the name of one of the constraint operators | Yes | The operator to apply to the context field. | "DATE_BEFORE" |
values | a list of strings | Yes | The list of values to apply the constraint operator to. | ["value a", "value b"] |
value | string | No | The value to apply the constraint operator to. | "15" |
inverted | boolean | No | Whether the result of the constraint will be negated or not. | false |
caseInsensitive | boolean string | No | Whether the constraint operator is case sensitive or not. Only applies to some string-based operators. | false |
Activation strategy
Example
{
"id": "64fbe72b-d107-4b26-b6b8-4fead08d286c",
"environment": "development",
"featureName": "my-feature",
"projectId": "my-project",
"strategyName": "flexibleRollout"
}
Description
Property | Type | Required | Description | Example value |
---|---|---|---|---|
id | GUID string | No | The ID of the strategy. | "64fbe72b-d107-4b26-b6b8-4fead08d286c" |
environment | string | Yes | The name of the strategy's environment. | "development" |
featureName | string | Yes | The name of the feature the strategy is applied to. | "my-feature" |
projectId | string | Yes | The name of the current project. | "my-project" |
strategyName | string | Yes | The name of the strategy. | "flexibleRollout" |