Skip to main content

/api/admin/segments

Availability

Segments are available to Unleash Pro and Unleash Enterprise users since Unleash 4.13.

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.

Get all segments​

Retrieve all segments that exist in this Unleash instance. Returns a list of segment objects.

Retrieve all existing segments.
GET <unleash-url>/api/admin/segments
Authorization: <API-token>
content-type: application/json
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.

Create a new segment.
POST <unleash-url>/api/admin/segments
Authorization: <API-token>
content-type: application/json

{
  "name": "my-segment",
  "description": "a segment description",
  "constraints": []
}
Example responses

201 Created​

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

400 Bad Request​

A segment with the provided name already exists.

Payload structure​

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

PropertyTypeRequiredDescriptionExample value
namestringYesThe name of the segment."mobile-users"
descriptionstringNoA description of the segment."This segment is for users on mobile devices."
constraintslist of constraint objectsYesThe constraints in this segment.[]

Get segment by ID​

Retrieves the segment with the specified ID.

Retrieve the segment with the provided ID.
GET <unleash-url>/api/admin/segments/<segment-id>
Authorization: <API-token>
content-type: application/json
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"
}

404 Not Found​

No segment with the provided ID exists.

Update an existing segment​

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

Update a segment with new data.
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": []
}
Example responses

204 No Content​

The update was successful. This response has no body.

404 Not Found​

No segment with the provided ID exists.

Delete a segment​

Delete the request with the specified ID.

Delete a segment.
DELETE <unleash-url>/api/admin/segments/<segment-id>
Authorization: <API-token>
content-type: application/json
Example responses

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.

List strategies that use a specific segment​

Retrieve all strategies that use the specified segment. Returns a list of activation strategy objects.

Retrieve all activation strategies that use the specified segment.
GET <unleash-url>/api/admin/segments/<segment-id>/strategies
Authorization: <API-token>
content-type: application/json
Example responses

200 OK​

[
  {
    "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.

List segments applied to a specific strategy​

Retrieve all segments that are applied to the specified strategy. Returns a list of segment objects.

Retrieve all segments that are used by the specified strategy.
GET <unleash-url>/api/admin/segments/strategies/<strategy-id>
Authorization: <API-token>
content-type: application/json
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"
  }
]

404 Not Found​

No strategy with the provided id exists.

Replace activation strategy segments​

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

Replace the segments to the specified strategy.
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
  ]
}

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

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.

Payload structure​

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

PropertyTypeRequiredDescriptionExample value
projectIdstringYesThe ID of the feature toggle's project."my-project"
strategyIdstringYesThe ID of the strategy."my-strategy"
environmentIdstringYesThe ID of the environment."development"
segmentIdslist of segment IDs (numbers)YesThe 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​

PropertyTypeRequiredDescriptionExample value
idnumberYesThe segment's ID.546
namestringYesThe segment's name"my-segment"
descriptionstringNoAn optional description of the segment."segment description"
constraintslist of constraint objectsYesThe list of constraint objects in the segment.[]
createdBystringNoAn identifier for who created the segment."you@example.com"
createdAttimestamp stringYesThe 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.

PropertyTypeRequiredDescriptionExample value
contextNamestringYesThe name of the context field targeted by the constraint."myContextField"
operatorstring, the name of one of the constraint operatorsYesThe operator to apply to the context field."DATE_BEFORE"
valuesa list of stringsYesThe list of values to apply the constraint operator to.["value a", "value b"]
valuestringNoThe value to apply the constraint operator to."15"
invertedbooleanNoWhether the result of the constraint will be negated or not.false
caseInsensitiveboolean stringNoWhether 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​

PropertyTypeRequiredDescriptionExample value
idGUID stringNoThe ID of the strategy."64fbe72b-d107-4b26-b6b8-4fead08d286c"
environmentstringYesThe name of the strategy's environment."development"
featureNamestringYesThe name of the feature the strategy is applied to."my-feature"
projectIdstringYesThe name of the current project."my-project"
strategyNamestringYesThe name of the strategy."flexibleRollout"