Unleash Import/Export API

openapi: 3.0.3
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:
    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
    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
          nullable: true
          example: Controls disabling of the comments section in case of an incident
          description: Detailed description of the feature
        archived:
          type: boolean
          example: true
          description: '`true` if the feature is archived'
        project:
          type: string
          example: dx-squad
          description: Name of the project the feature belongs to
        enabled:
          type: boolean
          example: true
          description: '`true` if the feature is enabled, otherwise `false`.'
        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
        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
        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, use the one in featureEnvironmentSchema
        environments:
          type: array
          items:
            $ref: '#/components/schemas/featureEnvironmentSchema'
          description: The list of environments where the feature can be used
        variants:
          type: array
          items:
            $ref: '#/components/schemas/variantSchema'
          description: The list of feature variants
          deprecated: true
        strategies:
          type: array
          items:
            type: object
          description: This was deprecated in v5 and will be removed in a future major version
          deprecated: true
        tags:
          type: array
          items:
            $ref: '#/components/schemas/tagSchema'
          nullable: true
          description: The list of feature tags
        children:
          type: array
          description: The list of child feature names. This is an experimental field and may change.
          items:
            type: string
            example: some-feature
        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'
        dependencies:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
            - feature
            properties:
              feature:
                description: The name of the parent feature
                type: string
                example: some-feature
              enabled:
                description: Whether the parent feature is enabled or not
                type: boolean
                example: true
              variants:
                description: The list of variants the parent feature should resolve to. Only valid when feature is enabled.
                type: array
                items:
                  example: some-feature-blue-variant
                  type: string
          description: The list of parent dependencies. This is an experimental field and may change.
        collaborators:
          type: object
          required:
          - users
          description: Information related to users who have made changes to this feature flage.
          properties:
            users:
              description: Users who have made any changes to this feature flags. The list is sorted in reverse chronological order (most recent changes first)
              type: array
              items:
                type: object
                required:
                - id
                - name
                - imageUrl
                description: A simple representation of a user.
                properties:
                  id:
                    description: The user's id
                    type: integer
                    example: 123
                  name:
                    description: The user's name, username, or email (prioritized in that order). If none of those are present, this property will be set to the string `unknown`
                    type: string
                    example: User
                  imageUrl:
                    description: The URL to the user's profile image
                    type: string
                    example: https://example.com/242x200.png
        links:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
            - id
            - url
            properties:
              id:
                type: string
                example: 01JTJNCJ5XVP2KPJFA03YRBZCA
                description: The id of the link
              url:
                type: string
                example: https://github.com/search?q=cleanupReminder&type=code
                description: The URL the feature is linked to
              title:
                type: string
                example: Github cleanup
                description: The description of the link
                nullable: true
              feature:
                type: string
                example: disable-comments
                description: The name of the feature this link belongs to
          description: The list of links. This is an experimental field and may change.
    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
          example: Github cleanup
          description: The description of the link
          nullable: true
      description: The link to any URL related to the feature
    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'
    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'
    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
    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'
    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
    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
    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
          nullable: true
          description: The icon of the tag type.
          example: not-really-used
        color:
          type: string
          nullable: true
          description: The hexadecimal color code for the tag type.
          example: '#FFFFFF'
          pattern: ^#[0-9A-Fa-f]{6}$
    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
    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
          nullable: false
        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
          format: date-time
          description: The date and time when the milestone was started.
          example: '2024-01-01T00:00:00.000Z'
          nullable: true
        transitionCondition:
          type: object
          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
          nullable: true
        progressionExecutedAt:
          type: string
          format: date-time
          description: The date and time when the milestone progression was executed.
          example: '2024-01-01T00:00:00.000Z'
          nullable: true
        pausedAt:
          type: string
          format: date-time
          description: The date and time when the milestone was paused.
          example: '2024-01-01T00:00:00.000Z'
          nullable: true
        strategies:
          type: array
          description: A list of strategies that are attached to this milestone.
          items:
            $ref: '#/components/schemas/releasePlanMilestoneStrategySchema'
    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'
    contextFieldSchema:
      type: object
      additionalProperties: false
      description: A representation of a [context field](https://docs.getunleash.io/concepts/unleash-context).
      required:
      - name
      properties:
        name:
          description: The name of the context field
          type: string
          example: userId
        description:
          description: The description of the context field.
          type: string
          nullable: true
          example: Used to uniquely identify users
        stickiness:
          description: Does this context field support being used for [stickiness](https://docs.getunleash.io/concepts/stickiness) calculations
          type: boolean
          example: true
        sortOrder:
          description: Used when sorting a list of context fields. Is also used as a tiebreaker if a list of context fields is sorted alphabetically.
          type: integer
          example: 900
        createdAt:
          description: When this context field was created
          type: string
          format: date-time
          nullable: true
          example: '2023-06-29T10:19:00.000Z'
        usedInFeatures:
          type: integer
          description: Number of projects where this context field is used in
          example: 3
          nullable: true
          minimum: 0
        usedInProjects:
          type: integer
          description: Number of proje

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