Unleash Search API

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