Unleash Segments API
Create, update, delete, and manage [segments](https://docs.getunleash.io/concepts/segments).
OpenAPI Specification
openapi: 3.0.3
info:
title: Unleash Admin Addons Segments API
version: 7.4.1
description: Create, update, and delete [Unleash addons](https://docs.getunleash.io/addons).
servers:
- url: https://app.unleash-instance.example.com
description: Your Unleash instance (replace with your actual URL)
security:
- apiKey: []
- bearerToken: []
tags:
- name: Segments
description: Create, update, delete, and manage [segments](https://docs.getunleash.io/concepts/segments).
paths:
/api/admin/segments/validate:
post:
summary: Validates If a Segment Name Exists
description: Uses the name provided in the body of the request to validate if the given name exists or not
tags:
- Segments
operationId: validateSegment
requestBody:
description: nameSchema
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/nameSchema'
responses:
'204':
description: This response has no body.
'400':
description: The request data does not match what we expect.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: ValidationError
description: The name of the error kind
message:
type: string
example: The request payload you provided doesn't conform to the schema. The .parameters property should be object. You sent [].
description: A description of what went wrong.
'401':
description: Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: AuthenticationRequired
description: The name of the error kind
message:
type: string
example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.
description: A description of what went wrong.
'409':
description: The provided resource can not be created or updated because it would conflict with the current state of the resource or with an already existing resource, respectively.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: NameExistsError
description: The name of the error kind
message:
type: string
example: There is already a feature called "my-awesome-feature".
description: A description of what went wrong.
'415':
description: The operation does not support request payloads of the provided type. Please ensure that you're using one of the listed payload types and that you have specified the right content type in the "content-type" header.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: ContentTypeerror
description: The name of the error kind
message:
type: string
example: We do not accept the content-type you provided (application/xml). Try using one of the content-types we do accept instead (application/json) and make sure the body is in the corresponding format.
description: A description of what went wrong.
/api/admin/segments/strategies/{strategyId}:
get:
tags:
- Segments
operationId: getSegmentsByStrategyId
summary: Get Strategy Segments
description: Retrieve all segments that are referenced by the specified strategy. Returns an empty list of segments if the strategy ID doesn't exist.
responses:
'200':
description: segmentsSchema
content:
application/json:
schema:
$ref: '#/components/schemas/segmentsSchema'
parameters:
- name: strategyId
in: path
required: true
schema:
type: string
/api/admin/segments/{id}/strategies:
get:
tags:
- Segments
operationId: getStrategiesBySegmentId
summary: Get Strategies That Reference Segment
description: Retrieve all strategies that reference the specified segment.
parameters:
- name: id
in: path
required: true
schema:
type: integer
description: a segment id
responses:
'200':
description: segmentStrategiesSchema
content:
application/json:
schema:
$ref: '#/components/schemas/segmentStrategiesSchema'
/api/admin/segments/{id}:
delete:
summary: Deletes a Segment by ID
description: Deletes a segment by its id, if not found returns a 409 error
parameters:
- name: id
in: path
required: true
schema:
type: integer
description: a segment id
tags:
- Segments
operationId: removeSegment
responses:
'204':
description: This response has no body.
'401':
description: Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: AuthenticationRequired
description: The name of the error kind
message:
type: string
example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.
description: A description of what went wrong.
'403':
description: The provided user credentials are valid, but the user does not have the necessary permissions to perform this operation
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: NoAccessError
description: The name of the error kind
message:
type: string
example: You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.
description: A description of what went wrong.
'409':
description: The provided resource can not be created or updated because it would conflict with the current state of the resource or with an already existing resource, respectively.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: NameExistsError
description: The name of the error kind
message:
type: string
example: There is already a feature called "my-awesome-feature".
description: A description of what went wrong.
put:
summary: Update Segment by ID
description: Updates the content of the segment with the provided payload. Requires `name` and `constraints` to be present. If `project` is not present, it will be set to `null`. Any other fields not specified will be left untouched.
tags:
- Segments
operationId: updateSegment
parameters:
- name: id
in: path
required: true
schema:
type: integer
description: a segment id
requestBody:
description: upsertSegmentSchema
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/upsertSegmentSchema'
responses:
'204':
description: This response has no body.
'400':
description: The request data does not match what we expect.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: ValidationError
description: The name of the error kind
message:
type: string
example: The request payload you provided doesn't conform to the schema. The .parameters property should be object. You sent [].
description: A description of what went wrong.
'401':
description: Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: AuthenticationRequired
description: The name of the error kind
message:
type: string
example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.
description: A description of what went wrong.
'403':
description: The provided user credentials are valid, but the user does not have the necessary permissions to perform this operation
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: NoAccessError
description: The name of the error kind
message:
type: string
example: You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.
description: A description of what went wrong.
'409':
description: The provided resource can not be created or updated because it would conflict with the current state of the resource or with an already existing resource, respectively.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: NameExistsError
description: The name of the error kind
message:
type: string
example: There is already a feature called "my-awesome-feature".
description: A description of what went wrong.
'415':
description: The operation does not support request payloads of the provided type. Please ensure that you're using one of the listed payload types and that you have specified the right content type in the "content-type" header.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: ContentTypeerror
description: The name of the error kind
message:
type: string
example: We do not accept the content-type you provided (application/xml). Try using one of the content-types we do accept instead (application/json) and make sure the body is in the corresponding format.
description: A description of what went wrong.
get:
summary: Get a Segment
description: Retrieves a segment based on its ID.
tags:
- Segments
operationId: getSegment
parameters:
- name: id
in: path
required: true
schema:
type: integer
description: a segment id
responses:
'200':
description: adminSegmentSchema
content:
application/json:
schema:
$ref: '#/components/schemas/adminSegmentSchema'
'404':
description: The requested resource was not found.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: NotFoundError
description: The name of the error kind
message:
type: string
example: Could not find the addon with ID "12345".
description: A description of what went wrong.
/api/admin/segments:
post:
summary: Create a New Segment
description: Creates a new segment using the payload provided
tags:
- Segments
operationId: createSegment
requestBody:
description: upsertSegmentSchema
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/upsertSegmentSchema'
responses:
'201':
headers:
location:
description: The location of the newly created resource.
schema:
type: string
format: uri
description: The resource was successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/adminSegmentSchema'
'400':
description: The request data does not match what we expect.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: ValidationError
description: The name of the error kind
message:
type: string
example: The request payload you provided doesn't conform to the schema. The .parameters property should be object. You sent [].
description: A description of what went wrong.
'401':
description: Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: AuthenticationRequired
description: The name of the error kind
message:
type: string
example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login.
description: A description of what went wrong.
'403':
description: The provided user credentials are valid, but the user does not have the necessary permissions to perform this operation
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: NoAccessError
description: The name of the error kind
message:
type: string
example: You need the "UPDATE_ADDON" permission to perform this action in the "development" environment.
description: A description of what went wrong.
'409':
description: The provided resource can not be created or updated because it would conflict with the current state of the resource or with an already existing resource, respectively.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: NameExistsError
description: The name of the error kind
message:
type: string
example: There is already a feature called "my-awesome-feature".
description: A description of what went wrong.
'415':
description: The operation does not support request payloads of the provided type. Please ensure that you're using one of the listed payload types and that you have specified the right content type in the "content-type" header.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: 9c40958a-daac-400e-98fb-3bb438567008
description: The ID of the error instance
name:
type: string
example: ContentTypeerror
description: The name of the error kind
message:
type: string
example: We do not accept the content-type you provided (application/xml). Try using one of the content-types we do accept instead (application/json) and make sure the body is in the corresponding format.
description: A description of what went wrong.
get:
summary: Get All Segments
description: Retrieves all segments that exist in this Unleash instance.
tags:
- Segments
operationId: getSegments
responses:
'200':
description: segmentsSchema
content:
application/json:
schema:
$ref: '#/components/schemas/segmentsSchema'
components:
schemas:
constraintSchema:
additionalProperties: false
type: object
required:
- contextName
- operator
description: A strategy constraint. For more information, refer to [the strategy constraint reference documentation](https://docs.getunleash.io/concepts/activation-strategies#constraints)
properties:
contextName:
description: The name of the context field that this constraint should apply to.
example: appName
type: string
operator:
description: The operator to use when evaluating this constraint. For more information about the various operators, refer to [the strategy constraint operator documentation](https://docs.getunleash.io/concepts/activation-strategies#constraint-operators).
type: string
enum:
- NOT_IN
- IN
- STR_ENDS_WITH
- STR_STARTS_WITH
- STR_CONTAINS
- NUM_EQ
- NUM_GT
- NUM_GTE
- NUM_LT
- NUM_LTE
- DATE_AFTER
- DATE_BEFORE
- SEMVER_EQ
- SEMVER_GT
- SEMVER_LT
example: IN
caseInsensitive:
description: Whether the operator should be case sensitive or not. Defaults to `false` (being case sensitive).
type: boolean
default: false
inverted:
description: Whether the result should be negated or not. If `true`, will turn a `true` result into a `false` result and vice versa.
type: boolean
default: false
values:
type: array
description: The context values that should be used for constraint evaluation. Use this property instead of `value` for properties that accept multiple values.
items:
type: string
example:
- my-app
- my-other-app
value:
description: The context value that should be used for constraint evaluation. Use this property instead of `values` for properties that only accept single values.
type: string
example: my-app
upsertSegmentSchema:
type: object
description: Data used to create or update a segment
required:
- name
- constraints
properties:
name:
description: The name of the segment
example: beta-users
type: string
description:
type: string
nullable: true
description: A description of what the segment is for
example: Users willing to help us test and build new features.
project:
type: string
nullable: true
description: The project the segment belongs to if any.
example: red-vista
constraints:
type: array
description: The list of constraints that make up this segment
items:
$ref: '#/components/schemas/constraintSchema'
nameSchema:
type: object
additionalProperties: false
required:
- name
description: An object with a name
properties:
name:
description: The name of the represented object.
example: betaUser
type: string
segmentsSchema:
description: Data containing a list of [segments](https://docs.getunleash.io/concepts/segments)
type: object
properties:
segments:
type: array
description: A list of segments
items:
$ref: '#/components/schemas/adminSegmentSchema'
segmentStrategiesSchema:
type: object
required:
- strategies
description: A collection of strategies belonging to a specified segment.
additionalProperties: false
properties:
strategies:
description: The list of strategies
type: array
items:
type: object
required:
- id
- featureName
- projectId
- environment
- strategyName
properties:
id:
type: string
description: The ID of the strategy
example: e465c813-cffb-4232-b184-82b1d6fe9d3d
featureName:
type: string
description: The name of the feature flag that this strategy belongs to.
example: new-signup-flow
projectId:
type: string
description: The ID of the project that the strategy belongs to.
example: red-vista
environment:
type: string
description: The ID of the environment that the strategy belongs to.
example: development
strategyName:
type: string
description: The name of the strategy's type.
example: flexibleRollout
changeRequestStrategies:
description: A list of strategies that use this segment in active change requests.
type: array
items:
type: object
required:
- featureName
- projectId
- environment
- strategyName
properties:
id:
type: string
description: The ID of the strategy. Not present on new strategies that haven't been added to the feature flag yet.
example: e465c813-cffb-4232-b184-82b1d6fe9d3d
featureName:
type: string
description: The name of the feature flag that this strategy belongs to.
example: new-signup-flow
projectId:
type: string
description: The ID of the project that the strategy belongs to.
example: red-vista
environment:
type: string
description: The ID of the environment that the strategy belongs to.
example: development
strategyName:
type: string
description: The name of the strategy's type.
example: flexibleRollout
adminSegmentSchema:
type: object
required:
- id
- name
- constraints
- createdAt
description: A description of a [segment](https://docs.getunleash.io/concepts/segments)
additionalProperties: false
properties:
id:
type: integer
description: The ID of this segment
example: 2
minimum: 0
name:
type: string
description: The name of this segment
example: ios-users
description:
type: string
nullable: true
description: The description for this segment
example: IOS users segment
constraints:
type: array
description: The list of constraints that are used in this segment
items:
$ref: '#/components/schemas/constraintSchema'
usedInFeatures:
type: integer
minimum: 0
description: The number of feature flags that use this segment. The number also includes the any flags with pending change requests that would add this segment.
example: 3
nullable: true
usedInProjects:
type: integer
minimum: 0
description: The number of projects that use this segment. The number includes any projects with pending change requests that would add this segment.
example: 2
nullable: true
project:
type: string
nullable: true
example: red-vista
description: The project the segment belongs to. Only present if the segment is a project-specific segment.
createdBy:
description: The creator's email or username
example: someone@example.com
type: string
nullable: true
createdAt:
type: string
format: date-time
description: When the segment was created
example: '2023-04-12T11:13:31.960Z'
securitySchemes:
apiKey:
type: apiKey
in: header
name: Authorization
description: API key needed to access this API
bearerToken:
type: http
scheme: bearer
description: API key needed to access this API, in Bearer token format