openapi: 3.0.3
info:
title: Unleash Admin Addons Search 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: Search
description: Search for features.
paths:
/api/admin/search/features:
get:
tags:
- Search
summary: Search and Filter Features
description: Search and filter by selected fields.
operationId: searchFeatures
parameters:
- name: query
schema:
type: string
example: feature_a
description: The search query for the feature name or tag
in: query
- name: project
schema:
type: string
example: IS:default
pattern: ^(IS|IS_NOT|IS_ANY_OF|IS_NONE_OF):(.*?)(,([a-zA-Z0-9_]+))*$
description: Id of the project where search and filter is performed. The project id can be specified with an operator. The supported operators are IS, IS_NOT, IS_ANY_OF, IS_NONE_OF.
in: query
- name: state
schema:
type: string
example: IS:active
pattern: ^(IS|IS_NOT|IS_ANY_OF|IS_NONE_OF):(.*?)(,([a-zA-Z0-9_]+))*$
description: The state of the feature active/stale. The state can be specified with an operator. The supported operators are IS, IS_NOT, IS_ANY_OF, IS_NONE_OF.
in: query
- name: lifecycle
schema:
type: string
example: IS:initial
pattern: ^(IS|IS_NOT|IS_ANY_OF|IS_NONE_OF):(.*?)(,([a-zA-Z0-9_]+))*$
description: The lifecycle stage of the feature. The stagee can be specified with an operator. The supported operators are IS, IS_NOT, IS_ANY_OF, IS_NONE_OF.
in: query
- name: type
schema:
type: string
example: IS:release
pattern: ^(IS|IS_NOT|IS_ANY_OF|IS_NONE_OF):(.*?)(,([a-zA-Z0-9_]+))*$
description: The feature flag type to filter by. The type can be specified with an operator. The supported operators are IS, IS_NOT, IS_ANY_OF, IS_NONE_OF.
in: query
- name: createdBy
schema:
type: string
example: IS:1
pattern: ^(IS|IS_NOT|IS_ANY_OF|IS_NONE_OF):(.*?)(,([a-zA-Z0-9_]+))*$
description: The feature flag creator to filter by. The creators can be specified with an operator. The supported operators are IS, IS_NOT, IS_ANY_OF, IS_NONE_OF.
in: query
- name: tag
schema:
type: string
pattern: ^(INCLUDE|DO_NOT_INCLUDE|INCLUDE_ALL_OF|INCLUDE_ANY_OF|EXCLUDE_IF_ANY_OF|EXCLUDE_ALL):([^:,]+:.+?)(,\s*[^:,]+:.+?)*$
example: INCLUDE:simple:my_tag
description: The list of feature tags to filter by. Feature tag has to specify a type and a value joined with a colon.
in: query
- name: segment
schema:
type: string
pattern: ^(INCLUDE|DO_NOT_INCLUDE|INCLUDE_ALL_OF|INCLUDE_ANY_OF|EXCLUDE_IF_ANY_OF|EXCLUDE_ALL):(.*?)(,([a-zA-Z0-9_]+))*$
example: INCLUDE:pro-users
description: The list of segments with operators to filter by. The segment valid operators are INCLUDE, DO_NOT_INCLUDE, INCLUDE_ALL_OF, INCLUDE_ANY_OF, EXCLUDE_IF_ANY_OF, EXCLUDE_ALL.
in: query
- name: status
schema:
type: array
items:
type: string
example: production:enabled
description: The list of feature environment status to filter by. Feature environment has to specify a name and a status joined with a colon.
in: query
- name: offset
schema:
type: string
example: '50'
description: The number of features to skip when returning a page. By default it is set to 0.
in: query
- name: limit
schema:
type: string
example: '50'
description: The number of feature environments to return in a page. By default it is set to 50.
in: query
- name: sortBy
schema:
type: string
example: type
description: The field to sort the results by. By default it is set to "createdAt".
in: query
- name: sortOrder
schema:
type: string
enum:
- asc
- desc
example: desc
description: The sort order for the sortBy. By default it is det to "asc".
in: query
- name: favoritesFirst
schema:
type: string
example: 'true'
description: The flag to indicate if the favorite features should be returned first. By default it is set to false.
in: query
- name: archived
schema:
type: string
example: IS:true
pattern: ^IS:(true|false)$
description: Whether to get results for archived feature flags or active feature flags. If `IS:true`, Unleash will return only archived flags. If `IS:false`, it will return only active flags.
in: query
- name: createdAt
schema:
type: string
example: IS_ON_OR_AFTER:2023-01-28
pattern: ^(IS_BEFORE|IS_ON_OR_AFTER):\d{4}-\d{2}-\d{2}$
description: The date the feature was created. The date can be specified with an operator. The supported operators are IS_BEFORE, IS_ON_OR_AFTER.
in: query
- name: lastSeenAt
schema:
type: string
example: IS_ON_OR_AFTER:2023-01-28
pattern: ^(IS_BEFORE|IS_ON_OR_AFTER):\d{4}-\d{2}-\d{2}$
description: The date the feature was last seen from metrics. The date can be specified with an operator. The supported operators are IS_BEFORE, IS_ON_OR_AFTER.
in: query
responses:
'200':
description: searchFeaturesSchema
content:
application/json:
schema:
$ref: '#/components/schemas/searchFeaturesSchema'
'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.
'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.
components:
schemas:
releasePlanSchema:
additionalProperties: false
description: Schema representing the creation of a release plan.
type: object
required:
- id
- discriminator
- name
- featureName
- environment
- createdByUserId
- createdAt
- milestones
- releasePlanTemplateId
properties:
id:
type: string
description: The release plan/template's ID. Release template IDs are ulids.
example: 01JB9GGTGQYEQ9D40R17T3YVW2
nullable: false
discriminator:
type: string
description: A field to distinguish between release plans and release templates.
example: plan
nullable: false
enum:
- plan
name:
type: string
description: The name of the release template.
example: My release plan
description:
type: string
description: A description of the release template.
example: This is my release plan
nullable: true
featureName:
type: string
description: The name of the feature that uses this release plan.
example: my-feature
environment:
type: string
description: The environment that this release plan is for.
example: production
createdByUserId:
type: number
description: 'Release template: The ID of the user who created this template.'
example: 53
nullable: false
createdAt:
type: string
format: date-time
description: The date and time that the release template was created.
example: '2022-01-01T00:00:00Z'
nullable: false
activeMilestoneId:
type: string
description: The ID of the currently active milestone in this release plan.
example: 01JB9GGTGQYEQ9D40R17T3YVW1
nullable: true
milestones:
type: array
description: A list of the milestones in this release template.
items:
$ref: '#/components/schemas/releasePlanMilestoneSchema'
releasePlanTemplateId:
type: string
description: The ID of the release plan template that this release plan is based on.
example: 01JB9GGTGQYEQ9D40R17T3YVW2
nullable: false
safeguards:
type: array
description: An array of safeguards configured for this release plan.
items:
$ref: '#/components/schemas/safeguardSchema'
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
releasePlanMilestoneStrategySchema:
additionalProperties: false
description: Schema representing the creation of a release plan milestone strategy.
type: object
required:
- id
- milestoneId
- sortOrder
- strategyName
properties:
id:
type: string
description: The milestone strategy's ID. Milestone strategy IDs are ulids.
example: 01JB9GGTGQYEQ9D40R17T3YVW3
nullable: false
milestoneId:
type: string
description: The ID of the milestone that this strategy belongs to.
example: 01JB9GGTGQYEQ9D40R17T3YVW1
sortOrder:
type: number
description: The order of the strategy in the list
example: 9999
title:
type: string
nullable: true
description: A descriptive title for the strategy
example: Gradual Rollout 25-Prod
strategyName:
type: string
description: The name of the strategy type
example: flexibleRollout
parameters:
description: An object containing the parameters for the strategy
example:
groupId: some_new
rollout: '25'
stickiness: sessionId
$ref: '#/components/schemas/parametersSchema'
constraints:
type: array
description: A list of the constraints attached to the strategy. See https://docs.getunleash.io/concepts/activation-strategies#constraints
example:
- values:
- '1'
- '2'
inverted: false
operator: IN
contextName: appName
caseInsensitive: false
items:
$ref: '#/components/schemas/constraintSchema'
variants:
type: array
description: Strategy level variants
items:
$ref: '#/components/schemas/createStrategyVariantSchema'
segments:
type: array
description: Ids of segments to use for this strategy
example:
- 1
- 2
items:
type: number
tagSchema:
type: object
description: Representation of a [tag](https://docs.getunleash.io/concepts/feature-flags#tags)
additionalProperties: false
required:
- value
- type
properties:
value:
type: string
description: The value of the tag.
minLength: 2
maxLength: 50
example: a-tag-value
type:
type: string
minLength: 2
maxLength: 50
description: The [type](https://docs.getunleash.io/concepts/feature-flags#tags) of the tag
example: simple
color:
type: string
description: The hexadecimal color code for the tag type.
example: '#FFFFFF'
pattern: ^#[0-9A-Fa-f]{6}$
nullable: true
overrideSchema:
type: object
additionalProperties: false
required:
- contextName
- values
description: An override for deciding which variant should be assigned to a user based on the context name
properties:
contextName:
description: The name of the context field used to determine overrides
type: string
example: userId
values:
description: Which values that should be overriden
type: array
items:
type: string
example:
- red
- blue
parametersSchema:
type: object
description: A list of parameters for a strategy
additionalProperties:
type: string
safeguardSchema:
type: object
required:
- id
- action
- triggerCondition
- impactMetric
description: A safeguard configuration for a release plan.
additionalProperties: false
properties:
id:
type: string
description: The unique ULID identifier for this safeguard
example: 01JB9GGTGQYEQ9D40R17T3YVW1
action:
type: object
required:
- type
- id
additionalProperties: false
description: The action to take when the safeguard is triggered.
properties:
type:
type: string
description: The type of action to perform.
example: pauseReleasePlanProgressions
id:
type: string
description: The ID of the release plan this safeguard applies to.
example: 01JB9GGTGQYEQ9D40R17T3YVW2
triggerCondition:
$ref: '#/components/schemas/safeguardTriggerConditionSchema'
description: The condition that triggers the safeguard.
impactMetric:
type: object
required:
- id
- metricName
- timeRange
- aggregationMode
- labelSelectors
additionalProperties: false
properties:
id:
type: string
description: The unique identifier for this impact metric
example: 01JB9GGTGQYEQ9D40R17T3YVW1
metricName:
type: string
description: The Prometheus metric series to query. It includes both unleash prefix and metric type and display name
example: unleash_counter_feature_toggle_usage_total
timeRange:
type: string
enum:
- hour
- day
- week
- month
description: The time range for the metric data.
example: day
aggregationMode:
type: string
description: The aggregation mode for the metric data.
enum:
- rps
- count
- avg
- sum
- p95
- p99
- p50
example: rps
labelSelectors:
type: object
additionalProperties:
type: array
items:
type: string
description: The selected labels and their values for filtering the metric data.
example:
environment:
- development
project:
- default
description: The metric configuration used to evaluate the safeguard condition.
featureSearchResponseSchema:
type: object
additionalProperties: false
required:
- name
- description
- dependencyType
- type
- project
- stale
- favorite
- impressionData
- createdAt
- createdBy
- environments
- segments
- archivedAt
description: A feature flag definition
properties:
name:
type: string
example: disable-comments
description: Unique feature name
type:
type: string
example: kill-switch
description: Type of the flag e.g. experiment, kill-switch, release, operational, permission
description:
type: string
nullable: true
example: Controls disabling of the comments section in case of an incident
description: Detailed description of the feature
dependencyType:
type: string
enum:
- parent
- child
- null
nullable: true
example: parent
description: The type of dependency. 'parent' means that the feature is a parent feature, 'child' means that the feature is a child feature.
project:
type: string
example: dx-squad
description: Name of the project the feature belongs to
stale:
type: boolean
example: false
description: '`true` if the feature is stale based on the age and feature type, otherwise `false`.'
favorite:
type: boolean
example: true
description: '`true` if the feature was favorited, otherwise `false`.'
impressionData:
type: boolean
example: false
description: '`true` if the impression data collection is enabled for the feature, otherwise `false`.'
createdAt:
type: string
format: date-time
nullable: true
example: '2023-01-28T15:21:39.975Z'
description: The date the feature was created
archivedAt:
type: string
format: date-time
nullable: true
example: '2023-01-29T15:21:39.975Z'
description: The date the feature was archived
lastSeenAt:
type: string
format: date-time
nullable: true
deprecated: true
example: '2023-01-28T16:21:39.975Z'
description: The date when metrics where last collected for the feature. This field was deprecated in v5 and will be removed in a future release, use the one in featureEnvironmentSchema
environments:
type: array
items:
$ref: '#/components/schemas/featureSearchEnvironmentSchema'
description: The list of environments where the feature can be used
segments:
type: array
description: The list of segments the feature is enabled for.
example:
- pro-users
- main-segment
items:
type: string
variants:
type: array
items:
$ref: '#/components/schemas/variantSchema'
description: The list of feature variants. This field was deprecated in v5
deprecated: true
strategies:
type: array
items:
type: object
description: This is a legacy field that was deprecated in v5
deprecated: true
tags:
type: array
items:
$ref: '#/components/schemas/tagSchema'
nullable: true
description: The list of feature tags
lifecycle:
type: object
description: Current lifecycle stage of the feature
additionalProperties: false
required:
- stage
- enteredStageAt
properties:
stage:
description: The name of the current lifecycle stage
type: string
enum:
- initial
- pre-live
- live
- completed
- archived
example: initial
status:
type: string
nullable: true
example: kept
description: The name of the detailed status of a given stage. E.g. completed stage can be kept or discarded.
enteredStageAt:
description: When the feature entered this stage
type: string
format: date-time
example: '2023-01-28T15:21:39.975Z'
createdBy:
type: object
description: User who created the feature flag
additionalProperties: false
required:
- id
- name
- imageUrl
properties:
id:
description: The user id
type: integer
example: 123
name:
description: Name of the user
type: string
example: User
imageUrl:
description: URL used for the user profile image
type: string
example: https://example.com/242x200.png
createStrategyVariantSchema:
type: object
description: This is an experimental property. It may change or be removed as we work on it. Please don't depend on it yet. A strategy variant allows you to attach any data to strategies instead of only returning `true`/`false`. Strategy variants take precedence over feature variants.
required:
- name
- weight
- weightType
- stickiness
properties:
name:
type: string
description: The variant name. Must be unique for this feature flag
example: blue_group
weight:
type: integer
description: The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on [variant weights](https://docs.getunleash.io/concepts/feature-flag-variants#variant-weight) for more information
minimum: 0
maximum: 1000
weightType:
description: Set to `fix` if this variant must have exactly the weight allocated to it. If the type is `variable`, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the [variant weight documentation](https://docs.getunleash.io/concepts/feature-flag-variants#variant-weight).
type: string
example: fix
enum:
- variable
- fix
stickiness:
type: string
description: The [stickiness](https://docs.getunleash.io/concepts/feature-flag-variants#variant-stickiness) to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time
example: custom.context.field
payload:
type: object
required:
- type
- value
description: Extra data configured for this variant
properties:
type:
description: The type of the value. Commonly used types are string, number, json and csv.
type: string
enum:
- json
- csv
- string
- number
value:
description: The actual value of payload
type: string
example:
type: json
value: '{"color": "red"}'
safeguardTriggerConditionSchema:
type: object
required:
- operator
- threshold
additionalProperties: false
description: The condition that triggers the safeguard.
properties:
operator:
type: string
enum:
- '>'
- <
description: The comparison operator for the threshold check.
example: '>'
threshold:
type: number
description: The threshold value to compare against.
example: 100
strategyVariantSchema:
type: object
additionalProperties: false
description: This is an experimental property. It may change or be removed as we work on it. Please don't depend on it yet. A strategy variant allows you to attach any data to strategies instead of only returning `true`/`false`. Strategy variants take precedence over feature variants.
required:
- name
- weight
- weightType
- stickiness
properties:
name:
type: string
description: The variant name. Must be unique for this feature flag
example: blue_group
weight:
type: integer
description: The weight is the likelihood of any one user getting this variant. It is an integer between 0 and 1000. See the section on [variant weights](https://docs.getunleash.io/concepts/feature-flag-variants#variant-weight) for more information
minimum: 0
maximum: 1000
weightType:
description: Set to `fix` if this variant must have exactly the weight allocated to it. If the type is `variable`, the weight will adjust so that the total weight of all variants adds up to 1000. Refer to the [variant weight documentation](https://docs.getunleash.io/concepts/feature-flag-variants#variant-weight).
type: string
example: fix
enum:
- variable
- fix
stickiness:
type: string
description: The [stickiness](https://docs.getunleash.io/concepts/feature-flag-variants#variant-stickiness) to use for distribution of this variant. Stickiness is how Unleash guarantees that the same user gets the same variant every time
example: custom.context.field
payload:
type: object
required:
- type
- value
description: Extra data configured for this variant
properties:
type:
description: The type of the value. Commonly used types are string, number, json and csv.
type: string
enum:
- json
- csv
- string
- number
value:
description: The actual value of payload
type: string
example:
type: json
value: '{"color": "red"}'
featureStrategySchema:
description: A single activation strategy configuration schema for a feature
type: object
additionalProperties: false
required:
- name
properties:
id:
type: string
description: A uuid for the feature strategy
example: 6b5157cb-343a-41e7-bfa3-7b4ec3044840
name:
type: string
description: The name or type of strategy
example: flexibleRollout
title:
type: string
description: A descriptive title for the strategy
example: Gradual Rollout 25-Prod
nullable: true
disabled:
type: boolean
description: A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs
example: false
nullable: true
featureName:
type: string
description: The name or feature the strategy is attached to
example: myAwesomeFeature
sortOrder:
type: number
description: The order of the strategy in the list
example: 9999
segments:
type: array
description: A list of segment ids attached to the strategy
example:
- 1
- 2
items:
type: number
constraints:
type: array
description: A list of the constraints attached to the strategy. See https://docs.getunleash.io/concepts/activation-strategies#constraints
items:
$ref: '#/components/schemas/constraintSchema'
variants:
type: array
description: Strategy level variants
items:
$ref: '#/components/schemas/strategyVariantSchema'
parameters:
$ref: '#/components/schemas/parametersSchema'
searchFeaturesSchema:
type: object
additionalProperties: false
required:
- features
description: A list of features matching search and filter criteria.
properties:
features:
type: array
items:
$ref: '#/components/schemas/featureSearchResponseSchema'
description: The full list of features in this project matching search and filter criteria.
total:
type: number
description: Total count of the features matching search and filter criteria
example: 10
feat
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/unleash/refs/heads/main/openapi/unleash-search-api-openapi.yml