Unleash Search API

openapi: 3.2.0
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:
    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
    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
    releasePlanMilestoneSchema:
      additionalProperties: false
      description: Schema representing the creation of a release plan milestone.
      type: object
      required:
      - id
      - name
      - sortOrder
      - releasePlanDefinitionId
      properties:
        id:
          type: string
          description: The milestone's ID. Milestone IDs are ulids.
          example: 01JB9GGTGQYEQ9D40R17T3YVW1
        name:
          type: string
          description: The name of the milestone.
          example: My milestone
        sortOrder:
          type: integer
          description: The order of the milestone in the release plan.
          example: 1
        releasePlanDefinitionId:
          type: string
          description: The ID of the release plan/template that this milestone belongs to.
          example: 01JB9GGTGQYEQ9D40R17T3YVW2
        startedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: The date and time when the milestone was started.
          example: '2024-01-01T00:00:00.000Z'
        transitionCondition:
          type:
          - object
          - 'null'
          additionalProperties: false
          required:
          - intervalMinutes
          properties:
            intervalMinutes:
              type: integer
              minimum: 1
              description: The interval in minutes before transitioning
              example: 30
          description: The condition configuration for the transition
        progressionExecutedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: The date and time when the milestone progression was executed.
          example: '2024-01-01T00:00:00.000Z'
        pausedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: The date and time when the milestone was paused.
          example: '2024-01-01T00:00:00.000Z'
        strategies:
          type: array
          description: A list of strategies that are attached to this milestone.
          items:
            $ref: '#/components/schemas/releasePlanMilestoneStrategySchema'
    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.
    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
          - 'null'
          description: A descriptive title for the strategy
          example: Gradual Rollout 25-Prod
        disabled:
          type:
          - boolean
          - 'null'
          description: A toggle to disable the strategy. defaults to false. Disabled strategies are not evaluated or returned to the SDKs
          example: false
        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'
    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
          - 'null'
          example: Controls disabling of the comments section in case of an incident
          description: Detailed description of the feature
        dependencyType:
          type:
          - string
          - 'null'
          enum:
          - parent
          - child
          - null
          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
          - 'null'
          format: date-time
          example: '2023-01-28T15:21:39.975Z'
          description: The date the feature was created
        archivedAt:
          type:
          - string
          - 'null'
          format: date-time
          example: '2023-01-29T15:21:39.975Z'
          description: The date the feature was archived
        lastSeenAt:
          type:
          - string
          - 'null'
          format: date-time
          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
          - 'null'
          items:
            $ref: '#/components/schemas/tagSchema'
          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
              - 'null'
              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
    variantSchema:
      type: object
      additionalProperties: false
      description: A variant allows for further separation of users into segments. See [our excellent documentation](https://docs.getunleash.io/concepts/feature-flag-variants#what-are-variants) for a more detailed description
      required:
      - name
      - weight
      properties:
        name:
          type: string
          description: The variants name. Is unique for this feature flag
          example: blue_group
        weight:
          type: number
          description: The weight is the likelihood of any one user getting this variant. It is a number 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
          type: string
          example: variable
          enum:
          - variable
          - fix
        stickiness:
          type: string
          description: '[Stickiness](https://docs.getunleash.io/concepts/feature-flag-variants#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
          additionalProperties: false
          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"}'
        overrides:
          description: Overrides assigning specific variants to specific users. The weighting system automatically assigns users to specific groups for you, but any overrides in this list will take precedence.
          type: array
          items:
            $ref: '#/components/schemas/overrideSchema'
    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
          - 'null'
          description: The hexadecimal color code for the tag type.
          example: '#FFFFFF'
          pattern: ^#[0-9A-Fa-f]{6}$
    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
    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
        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
          - 'null'
          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
    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
    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"}'
    parametersSchema:
      type: object
      description: A list of parameters for a strategy
      additionalProperties:
        type: string
    featureSearchEnvironmentSchema:
      type: object
      additionalProperties: false
      required:
      - name
      - enabled
      - type
      description: A detailed description of the feature environment
      properties:
        name:
          type: string
          

# --- 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