Unleash Import/Export API

openapi: 3.2.0
info:
  title: Unleash Admin Addons Import/Export 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: Import/Export
  description: '[Import and export](https://docs.getunleash.io/concepts/import-export) the state of your Unleash instance.'
paths:
  /api/admin/features-batch/export:
    post:
      tags:
      - Import/Export
      operationId: exportFeatures
      requestBody:
        description: exportQuerySchema
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/exportQuerySchema'
      responses:
        '200':
          description: exportResultSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exportResultSchema'
        '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.
      description: Exports all features listed in the `features` property from the environment specified in the request body. If set to `true`, the `downloadFile` property will let you download a file with the exported data. Otherwise, the export data is returned directly as JSON. Refer to the documentation for more information about [Unleash's export functionality](https://docs.getunleash.io/concepts/import-export#export-feature-flags).
      summary: Export Feature Flags From an Environment
  /api/admin/features-batch/validate:
    post:
      tags:
      - Import/Export
      operationId: validateImport
      requestBody:
        description: importTogglesSchema
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/importTogglesSchema'
      responses:
        '200':
          description: importTogglesValidateSchema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/importTogglesValidateSchema'
        '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.
      summary: Validate Feature Import Data
      description: Validates a feature flag data set. Checks whether the data can be imported into the specified project and environment. The returned value is an object that contains errors, warnings, and permissions required to perform the import, as described in the [import documentation](https://docs.getunleash.io/concepts/import-export#import-feature-flags).
  /api/admin/features-batch/import:
    post:
      tags:
      - Import/Export
      operationId: importToggles
      requestBody:
        description: importTogglesSchema
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/importTogglesSchema'
      responses:
        '200':
          description: This response has no body.
        '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.
      summary: Import Feature Flags
      description: '[Import feature flags](https://docs.getunleash.io/concepts/import-export#import-feature-flags) into a specific project and environment.'
components:
  schemas:
    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
    featureLinkSchema:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          example: https://github.com/search?q=cleanupReminder&type=code
          description: The URL the feature is linked to
        title:
          type:
          - string
          - 'null'
          example: Github cleanup
          description: The description of the link
      description: The link to any URL related to the feature
    featureDependenciesSchema:
      type: object
      description: Feature dependency connection between a child feature and its dependencies
      required:
      - feature
      - dependencies
      additionalProperties: false
      properties:
        feature:
          type: string
          description: The name of the child feature.
          example: child_feature
        dependencies:
          type: array
          description: List of parent features for the child feature
          items:
            $ref: '#/components/schemas/dependentFeatureSchema'
    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}$
    featureTagSchema:
      type: object
      description: Describes a tag applied to a feature
      additionalProperties: false
      required:
      - featureName
      - tagValue
      properties:
        featureName:
          type: string
          example: my-feature
          description: The name of the feature this tag is applied to
        tagType:
          type: string
          example: simple
          description: The [type](https://docs.getunleash.io/concepts/feature-flags#tags) of the tag
        tagValue:
          type: string
          example: my-tag
          description: The value of the tag
        type:
          deprecated: true
          type: string
          description: The [type](https://docs.getunleash.io/concepts/feature-flags#tags) of the tag. This property is deprecated and will be removed in a future version of Unleash. Superseded by the `tagType` property.
        value:
          deprecated: true
          type: string
          description: The value of the tag. This property is deprecated and will be removed in a future version of Unleash. Superseded by the `tagValue` property.
        createdByUserId:
          type:
          - number
          - 'null'
          example: 1
          description: The id of the user who created this tag
    tagTypeSchema:
      type: object
      additionalProperties: false
      description: A tag type.
      required:
      - name
      properties:
        name:
          type: string
          description: The name of the tag type.
          example: color
        description:
          type: string
          description: The description of the tag type.
          example: A tag type for describing the color of a tag.
        icon:
          type:
          - string
          - 'null'
          description: The icon of the tag type.
          example: not-really-used
        color:
          type:
          - string
          - 'null'
          description: The hexadecimal color code for the tag type.
          example: '#FFFFFF'
          pattern: ^#[0-9A-Fa-f]{6}$
    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"}'
    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"}'
    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'
    exportResultSchema:
      type: object
      additionalProperties: false
      description: The result of the export operation, providing you with the feature flag definitions, strategy definitions and the rest of the elements relevant to the features (tags, environments etc.)
      required:
      - features
      - featureStrategies
      - tagTypes
      properties:
        features:
          type: array
          description: All the exported features.
          example:
          - name: my-feature
            description: best feature ever
            type: release
            project: default
            stale: false
            impressionData: false
            archived: false
          items:
            $ref: '#/components/schemas/featureSchema'
        featureStrategies:
          type: array
          description: All strategy instances that are used by the exported features in the `features` list.
          example:
          - name: flexibleRollout
            id: 924974d7-8003-43ee-87eb-c5f887c06fd1
            featureName: my-feature
            title: Rollout 50%
            parameters:
              groupId: default
              rollout: '50'
              stickiness: random
            constraints: []
            disabled: false
            segments:
            - 1
          items:
            $ref: '#/components/schemas/featureStrategySchema'
        featureEnvironments:
          type: array
          description: Environment-specific configuration for all the features in the `features` list. Includes data such as whether the feature is enabled in the selected export environment, whether there are any variants assigned, etc.
          example:
          - enabled: true
            featureName: my-feature
            environment: development
            variants:
            - name: a
              weight: 500
              overrides: []
              stickiness: random
              weightType: variable
            - name: b
              weight: 500
              overrides: []
              stickiness: random
              weightType: variable
            name: variant-testing
          items:
            $ref: '#/components/schemas/featureEnvironmentSchema'
        contextFields:
          type: array
          description: A list of all the context fields that are in use by any of the strategies in the `featureStrategies` list.
          example:
          - name: appName
            description: Allows you to constrain on application name
            stickiness: false
            sortOrder: 2
            legalValues: []
          items:
            $ref: '#/components/schemas/contextFieldSchema'
        featureTags:
          type: array
          description: A list of all the tags that have been applied to any of the features in the `features` list.
          example:
          - featureName: my-feature
            tagType: simple
            tagValue: user-facing
          items:
            $ref: '#/components/schemas/featureTagSchema'
        segments:
          type: array
          description: A list of all the segments that are used by the strategies in the `featureStrategies` list.
          example:
          - id: 1
            name: new-segment-name
          items:
            type: object
            additionalProperties: false
            required:
            - id
            - name
            properties:
              id:
                type: number
              name:
                type: string
        tagTypes:
          type: array
          description: A list of all of the tag types that are used in the `featureTags` list.
          example:
          - name: simple
            description: Used to simplify filtering of features
            icon: '#'
          items:
            $ref: '#/components/schemas/tagTypeSchema'
        dependencies:
          type: array
          description: A list of all the dependencies for features in `features` list.
          items:
            $ref: '#/components/schemas/featureDependenciesSchema'
        links:
          type: array
          description: A list of links for features in `features` list.
          items:
            $ref: '#/components/schemas/featureLinksSchema'
    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
    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'
    importTogglesSchema:
      type: object
      required:
      - project
      - environment
      - data
      additionalProperties: false
      description: The result of the export operation for a project and environment, used at import
      properties:
        project:
          type: string
          example: My awesome project
          description: The exported [project](https://docs.getunleash.io/concepts/projects)
        environment:
          type: string
          example: development
          description: The exported [environment](https://docs.getunleash.io/concepts/environments)
        data:
          $ref: '#/components/schemas/exportResultSchema'
    importTogglesValidateItemSchema:
      type: object
      required:
      - message
      - affectedItems
      additionalProperties: false
      description: A description of an error or warning pertaining to a feature flag import job.
      properties:
        message:
          type: string
          description: The validation error message
          example: 'You cannot import a feature that already exist in other projects. You already have the following features defined outside of project default:'
        affectedItems:
          type: array
          description: 'The items affected by this error message '
          example:
          - some-feature-a
          - some-feature-b
          items:
            type: string
    legalValueSchema:
      type: object
      additionalProperties: false
      description: Describes a legal value. Typically used to limit possible values for contextFields or strategy properties
      required:
      - value
      properties:
        value:
          description: The valid value
          type: string
          example: '#c154c1'
        description:
          description: Describes this specific legal value
          type: string
          example: Deep fuchsia
    dependentFeatureSchema:
      type: object
      description: Feature dependency on a parent feature in read model
      required:
      - feature
      additionalProperties: false
      properties:
        feature:
          type: string
          description: The name of the feature we depend on.
          example: parent_feature
        enabled:
          type: boolean
          description: Whether the parent feature should be enabled. When `false` variants are ignored. `true` by default.
          example: false
        variants:
          type: array
          description: The list of variants the parent feature should resolve to. Leave empty when you only want to check the `enabled` status.
          items:
            type: string
          example:
          - variantA
          - variantB
    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
    featureSchema:
      type: object
      additionalProperties: false
      required:
      - name
      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'
       

# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/unleash/refs/heads/main/openapi/unleash-import-export-api-openapi.yml