Microsoft Fabric Upgrade API

openapi: 3.2.0
info:
  title: Microsoft Fabric Workload Items REST Upgrade API
  version: v1
  x-source: 'https://github.com/microsoft/fabric-rest-api-specs (bundled from openapi/_original/fabric-rest-api-specs: anomalyDetector/swagger.json, apacheAirflowJob/swagger.json, appBackend/swagger.json, azureDatabricksStorage/swagger.json, copyJob/swagger.json, cosmosDbDatabase/swagger.json, dashboard/swagger.json, dataAgent/swagger.json, dataBuildToolJob/swagger.json, dataPipeline/swagger.json, dataflow/swagger.json, datamart/swagger.json, deploymentPlan/swagger.json, digitalTwinBuilder/swagger.json, digitalTwinBuilderFlow/swagger.json, environment/swagger.json, eventSchemaSet/swagger.json, eventhouse/swagger.json, eventstream/swagger.json, graphModel/swagger.json, graphQLApi/swagger.json, graphQuerySet/swagger.json, kqlDashboard/swagger.json, kqlDatabase/swagger.json, kqlQueryset/swagger.json, lakehouse/swagger.json, map/swagger.json, mirroredAzureDatabricksCatalog/swagger.json, mirroredCatalog/swagger.json, mirroredDatabase/swagger.json, mirroredWarehouse/swagger.json, mlExperiment/swagger.json, mlModel/swagger.json, monitoring/swagger.json, mountedDataFactory/swagger.json, notebook/swagger.json, ontology/swagger.json, operationsAgent/swagger.json, orgApp/swagger.json, orgAppAudience/swagger.json, paginatedReport/swagger.json, plan/swagger.json, policySet/swagger.json, realTimeIntelligence/swagger.json, reflex/swagger.json, report/swagger.json, semanticModel/swagger.json, snowflakeDatabase/swagger.json, spark/swagger.json, sparkjobdefinition/swagger.json, sqlDatabase/swagger.json, sqlEndpoint/swagger.json, userDataFunction/swagger.json, variableLibrary/swagger.json, warehouse/swagger.json)'
servers:
- url: https://api.fabric.microsoft.com/v1
security: []
tags:
- name: Upgrade
paths:
  /workspaces/{workspaceId}/dataflows/gen1UpgradeReadinessResults:
    get:
      summary: Lists Gen1 dataflow upgrade readiness results in the specified workspace
      description: '> [!NOTE]

        > Gen1 dataflow upgrade is currently in Preview (learn more).


        This API supports pagination.


        Evaluates all Gen1 dataflows in the specified workspace and returns a deterministic readiness verdict with the reasons behind it. Gen2 dataflows are excluded.


        ## Permissions


        The caller must have a *viewer* or higher workspace role. The operation returns readiness results for all Gen1 dataflows in the workspace without ownership filtering.


        ## Required Delegated Scopes


        Dataflow.Read.All or Dataflow.ReadWrite.All or Item.Read.All or Item.ReadWrite.All


        ## Limitations


        - The operation evaluates all Gen1 dataflows in the workspace and does not support selecting an individual dataflow.

        - Server-side filtering and sorting are not supported.

        - The page size must be between 1 and 30 when specified.


        ## Microsoft Entra supported identities


        This API supports the Microsoft identities listed in this section.


        | Identity | Support |

        |-|-|

        | User | Yes |

        | Service principal and Managed identities | Yes |


        ## Interface'
      tags:
      - Upgrade
      operationId: Upgrade_ListReadiness
      x-ms-pageable:
        nextLinkName: continuationUri
      parameters:
      - in: path
        name: workspaceId
        description: The workspace ID.
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: pageSize
        description: The maximum number of results per page. The value must be between 1 and 30. When omitted, the server selects the page size.
        required: false
        schema:
          type: integer
          format: int32
          maximum: 30
          minimum: 1
      - in: query
        name: continuationToken
        description: A token for retrieving the next page of results.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataflowUpgradeReadinessList'
        '429':
          description: The service rate limit was exceeded. The server returns a `Retry-After` header indicating, in seconds, how long the client must wait before sending additional requests.
          x-ms-error-response: true
          headers:
            Retry-After:
              description: The number of seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: 'Common error codes:


            * WorkspaceNotFound - The specified workspace does not exist.


            * InsufficientPrivileges - The caller does not have access to the workspace.


            * InvalidParameter - The page size is outside the allowed range.


            * InvalidContinuationToken - The continuation token is invalid or has been altered.


            * FeatureNotAvailable - The operation is not enabled for the caller''s tenant.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /workspaces/{workspaceId}/dataflows/gen1Upgrade:
    post:
      summary: Upgrades Gen1 dataflows in the specified workspace
      description: '> [!NOTE]

        > Gen1 dataflow upgrade is currently in Preview (learn more).


        This API supports long running operations (LRO).


        Upgrades a caller-supplied batch of Gen1 dataflows to Dataflow Gen2 in place. Each successful upgrade preserves the dataflow identifier and workspace. The batch supports partial success. The operation returns the batch result synchronously when processing completes immediately, or returns an accepted response for asynchronous processing and makes the result available through the long-running operation.


        ## Permissions


        The caller must own each dataflow being upgraded or have the *admin* workspace role. Authorization is evaluated independently for each dataflow; an unauthorized dataflow is returned as a failed result row without failing the batch request.


        ## Required Delegated Scopes


        Dataflow.ReadWrite.All or Item.ReadWrite.All


        ## Limitations


        - Each request must contain between 1 and 50 dataflows from the specified workspace.

        - The request body must not exceed 13 KiB (13,312 bytes), including whitespace.

        - Upgrades run in place and do not support cross-workspace targets.

        - Cancellation is not supported.


        ## Microsoft Entra supported identities


        This API supports the Microsoft identities listed in this section.


        | Identity | Support |

        |-|-|

        | User | Yes |

        | Service principal and Managed identities | Yes |


        ## Interface'
      tags:
      - Upgrade
      operationId: Upgrade_UpgradeDataflows
      x-ms-fabric-sdk-long-running-operation: true
      parameters:
      - in: path
        name: workspaceId
        description: The workspace ID.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataflowUpgradeResult'
        '202':
          description: Request accepted, the Gen1 dataflow upgrade is in progress. After the operation reaches a terminal state, retrieve the `DataflowUpgradeResult` payload by using the long running operations (LRO) APIs.
          headers:
            Location:
              description: The URL of the operation status, which can be used to track the operation state.
              schema:
                type: string
            x-ms-operation-id:
              description: The operation ID which can be used with long running operations (LRO) APIs to track the operation state and get the result.
              schema:
                type: string
                format: uuid
            Retry-After:
              description: The number of seconds to wait before retrying the request.
              schema:
                type: integer
        '429':
          description: The service rate limit was exceeded. The server returns a `Retry-After` header indicating, in seconds, how long the client must wait before sending additional requests.
          x-ms-error-response: true
          headers:
            Retry-After:
              description: The number of seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: 'Common error codes:


            * WorkspaceNotFound - The specified workspace does not exist.


            * InvalidItemsCount - The request contains fewer than 1 or more than 50 dataflows.


            * InvalidParameter - A dataflow entry is malformed.


            * InsufficientPrivileges - The caller does not have access to the workspace.


            * FeatureNotAvailable - The operation is not enabled for the caller''s tenant.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpgradeGen1DataflowsRequest'
        description: The Gen1 dataflow upgrade request payload.
        required: true
components:
  schemas:
    DataflowUpgradeReadinessList:
      description: A paginated list of Gen1 dataflow upgrade readiness results.
      type: object
      required:
      - value
      properties:
        value:
          description: The Gen1 dataflow upgrade readiness results.
          type: array
          items:
            $ref: '#/components/schemas/DataflowUpgradeReadiness'
          readOnly: true
      allOf:
      - $ref: '#/components/schemas/PaginatedResponse'
    DataflowUpgradeReadinessStatus:
      description: The Gen1 dataflow upgrade readiness status. Additional DataflowUpgradeReadinessStatus types may be added over time.
      type: string
      enum:
      - Unknown
      - ReadyToMigrate
      - NeedsAttention
      - UpgradeUnavailable
      x-ms-enum:
        name: DataflowUpgradeReadinessStatus
        modelAsString: true
        values:
        - value: Unknown
          description: The readiness assessment could not be completed and should be reported for investigation.
        - value: ReadyToMigrate
          description: The upgrade is expected to succeed without changes before or after the upgrade.
        - value: NeedsAttention
          description: The upgrade is expected to succeed, but follow-up changes may be needed or the upgrade may adjust the dataflow automatically.
        - value: UpgradeUnavailable
          description: The upgrade is expected to fail until the reported reasons are resolved.
    Gen1DataflowUpgradeTarget:
      description: A Gen1 dataflow targeted for an in-place upgrade.
      type: object
      required:
      - id
      properties:
        id:
          description: The identifier of the Gen1 dataflow to upgrade. The dataflow must belong to the specified workspace.
          type: string
          format: uuid
          readOnly: false
    ErrorResponse:
      description: The error response.
      required:
      - message
      - errorCode
      allOf:
      - $ref: '#/components/schemas/ErrorResponseDetails'
      properties:
        requestId:
          type: string
          format: uuid
          description: ID of the request associated with the error.
          readOnly: true
        moreDetails:
          description: List of additional error details.
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponseDetails'
          readOnly: true
        isRetriable:
          type: boolean
          description: When true, the request can be retried. Use the `Retry-After` response header to determine the delay, if available.
          readOnly: true
    UpgradeGen1DataflowsRequest:
      description: The request payload for upgrading Gen1 dataflows.
      type: object
      required:
      - dataflows
      properties:
        dataflows:
          description: The Gen1 dataflows to upgrade in the specified workspace.
          type: array
          minItems: 1
          maxItems: 50
          items:
            $ref: '#/components/schemas/Gen1DataflowUpgradeTarget'
          readOnly: false
    DataflowUpgradeReasonCode:
      description: The reason for a Gen1 dataflow upgrade readiness result. Additional DataflowUpgradeReasonCode types may be added over time.
      type: string
      enum:
      - MightBeAccessedByDirectQuery
      - HasByolAsStorage
      - HasIncrementalRefresh
      - HasLinkedEntities
      - IsReferencedByLinkedEntities
      - ServiceThrottled
      - HasUnsupportedNameCharacters
      - DisplayNameAlreadyInUse
      - ExceedsGen2QueryLimit
      - HasUnresolvedConnections
      - AssessmentUnavailable
      x-ms-enum:
        name: DataflowUpgradeReasonCode
        modelAsString: true
        values:
        - value: MightBeAccessedByDirectQuery
          description: The dataflow might be accessed through DirectQuery.
        - value: HasByolAsStorage
          description: The dataflow uses bring-your-own-lake storage.
        - value: HasIncrementalRefresh
          description: The dataflow uses incremental refresh.
        - value: HasLinkedEntities
          description: The dataflow has linked entities.
        - value: IsReferencedByLinkedEntities
          description: The dataflow is referenced by linked entities in other dataflows.
        - value: ServiceThrottled
          description: The readiness assessment was throttled and may succeed when retried later.
        - value: HasUnsupportedNameCharacters
          description: The display name contains characters that are unsupported by Dataflow Gen2 and are sanitized during the upgrade.
        - value: DisplayNameAlreadyInUse
          description: The sanitized display name is already in use and is prefixed during the upgrade.
        - value: ExceedsGen2QueryLimit
          description: The dataflow has more load-enabled queries than Dataflow Gen2 supports.
        - value: HasUnresolvedConnections
          description: One or more data source connections could not be resolved and must be recreated or rebound before the upgrade.
        - value: AssessmentUnavailable
          description: The readiness assessment could not run and should be reported for investigation.
    DataflowUpgradeReadinessReason:
      description: A reason contributing to a Gen1 dataflow upgrade readiness verdict.
      type: object
      required:
      - status
      - code
      - message
      properties:
        status:
          $ref: '#/components/schemas/DataflowUpgradeReadinessStatus'
        code:
          $ref: '#/components/schemas/DataflowUpgradeReasonCode'
        message:
          description: The human-readable message accompanying the reason code.
          type: string
          readOnly: true
    DataflowUpgradeRequiredAction:
      description: A change required before a Gen1 dataflow can be upgraded.
      type: object
      required:
      - status
      - code
      - message
      properties:
        status:
          $ref: '#/components/schemas/DataflowUpgradeReadinessStatus'
        code:
          $ref: '#/components/schemas/DataflowUpgradeReasonCode'
        message:
          description: The human-readable description of the required change.
          type: string
          readOnly: true
    DataflowUpgradeReadiness:
      description: The upgrade readiness assessment for a Gen1 dataflow.
      type: object
      required:
      - id
      - displayName
      - status
      properties:
        id:
          description: The identifier of the assessed Gen1 dataflow.
          type: string
          format: uuid
          readOnly: true
        displayName:
          description: The display name of the Gen1 dataflow.
          type: string
          readOnly: true
        status:
          $ref: '#/components/schemas/DataflowUpgradeReadinessStatus'
        reasons:
          description: The reasons behind the readiness verdict. This property is omitted when the status is `ReadyToMigrate` and is always present when the status is `Unknown`.
          type: array
          items:
            $ref: '#/components/schemas/DataflowUpgradeReadinessReason'
          readOnly: true
    ErrorResponseDetails:
      description: The error response details.
      type: object
      required:
      - message
      - errorCode
      properties:
        errorCode:
          type: string
          description: A specific identifier that provides information about an error condition, allowing for standardized communication between our service and its users.
          readOnly: true
        message:
          type: string
          description: A human readable representation of the error.
          readOnly: true
        relatedResource:
          $ref: '#/components/schemas/ErrorRelatedResource'
        parameters:
          description: Structured parameters providing additional machine-readable context about the error.
          type: array
          items:
            $ref: '#/components/schemas/ErrorParameter'
          readOnly: true
    DataflowMigrationStatus:
      description: The outcome of a Gen1 dataflow migration. Additional DataflowMigrationStatus types may be added over time.
      type: string
      enum:
      - Unknown
      - Succeeded
      - Failed
      x-ms-enum:
        name: DataflowMigrationStatus
        modelAsString: true
        values:
        - value: Unknown
          description: The migration outcome was not populated and indicates a service defect if returned.
        - value: Succeeded
          description: The dataflow was upgraded successfully.
        - value: Failed
          description: The dataflow failed to upgrade.
    ErrorRelatedResource:
      description: The error related resource details object.
      type: object
      required:
      - resourceId
      - resourceType
      properties:
        resourceId:
          type: string
          description: The resource ID that's involved in the error.
          readOnly: true
        resourceType:
          type: string
          description: The type of the resource that's involved in the error.
          readOnly: true
    DataflowMigration:
      description: The migration result for a Gen1 dataflow.
      type: object
      required:
      - dataflowId
      - dataflowName
      - targetDataflowName
      - workspaceId
      - workspaceName
      - assessmentStatus
      - migrationStatus
      properties:
        dataflowId:
          description: The identifier of the dataflow, which is preserved by a successful in-place upgrade.
          type: string
          format: uuid
          readOnly: true
        dataflowName:
          description: The source Gen1 dataflow display name.
          type: string
          readOnly: true
        targetDataflowName:
          description: The resulting Dataflow Gen2 display name, which may differ from the source display name.
          type: string
          readOnly: true
        workspaceId:
          description: The identifier of the workspace containing the dataflow.
          type: string
          format: uuid
          readOnly: true
        workspaceName:
          description: The display name of the workspace containing the dataflow.
          type: string
          readOnly: true
        assessmentStatus:
          $ref: '#/components/schemas/DataflowUpgradeReadinessStatus'
        requiredActions:
          description: The changes required before the dataflow can be upgraded. This property is omitted when no changes are required.
          type: array
          items:
            $ref: '#/components/schemas/DataflowUpgradeRequiredAction'
          readOnly: true
        migrationStatus:
          $ref: '#/components/schemas/DataflowMigrationStatus'
        migrationEndDateTime:
          description: The time when the dataflow migration reached a terminal state. This property is omitted when the time is not available. When present, the value is in UTC, using the YYYY-MM-DDTHH:mm:ssZ format.
          type: string
          format: date-time
          readOnly: true
        migrationError:
          description: The failure detail for the dataflow migration. This property is present only when the migration status is `Failed`, and `isRetriable` is always included. The `requestId` contains the upgrade operation ID. The error code is one of `InsufficientPrivileges`, `DataflowNotFound`, `DataflowBusy`, `DataflowRequiresChanges`, `CapacityOrLicenseNotSupported`, or `UpgradeFailed`.
          allOf:
          - $ref: '#/components/schemas/ErrorResponse'
          - type: object
            required:
            - isRetriable
            properties:
              isRetriable:
                description: Indicates whether the dataflow migration can be retried.
                type: boolean
                readOnly: true
          readOnly: true
    DataflowUpgradeResult:
      description: The result of a Gen1 dataflow upgrade batch.
      type: object
      required:
      - summary
      - migrations
      properties:
        summary:
          $ref: '#/components/schemas/DataflowUpgradeSummary'
        migrations:
          description: The migration result for each requested dataflow.
          type: array
          items:
            $ref: '#/components/schemas/DataflowMigration'
          readOnly: true
    PaginatedResponse:
      properties:
        continuationToken:
          type: string
          description: The token for the next result set batch. If there are no more records, it's removed from the response.
        continuationUri:
          type: string
          description: The URI of the next result set batch. If there are no more records, it's removed from the response.
    ErrorParameter:
      description: A structured parameter providing additional machine-readable context about an error.
      type: object
      properties:
        name:
          type: string
          description: The parameter identifier.
          readOnly: true
        value:
          type: string
          description: The parameter value.
          readOnly: true
        message:
          type: string
          description: A human-readable description of the parameter's meaning.
          readOnly: true
    DataflowUpgradeSummary:
      description: The roll-up counts for a Gen1 dataflow upgrade batch.
      type: object
      required:
      - totalCount
      - succeededCount
      - failedCount
      properties:
        totalCount:
          description: The total number of dataflows in the request.
          type: integer
          format: int32
          readOnly: true
        succeededCount:
          description: The number of dataflows that were upgraded successfully.
          type: integer
          format: int32
          readOnly: true
        failedCount:
          description: The number of dataflows that failed to upgrade.
          type: integer
          format: int32
          readOnly: true