Microsoft Fabric Recoverable Items API

openapi: 3.2.0
info:
  title: Microsoft Fabric Platform REST Recoverable Items API
  version: v1
  x-source: 'https://github.com/microsoft/fabric-rest-api-specs (bundled from openapi/_original/fabric-rest-api-specs: platform/swagger.json)'
servers:
- url: https://api.fabric.microsoft.com/v1
security: []
tags:
- name: RecoverableItems
paths:
  /workspaces/{workspaceId}/recoverableItems:
    get:
      summary: Lists recoverable items in a workspace
      description: '## Permissions


        The caller must have a *viewer* workspace role.


        ## Required Delegated Scopes


        Workspace.Read.All or Workspace.ReadWrite.All


        ## 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:
      - RecoverableItems
      operationId: RecoverableItems_ListRecoverableItems
      x-ms-pageable:
        nextLinkName: continuationUri
      parameters:
      - in: path
        name: workspaceId
        description: The workspace ID.
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: type
        description: The recoverable item's type.
        required: false
        schema:
          type: string
      - in: query
        name: continuationToken
        description: A token for retrieving the next page of results.
        required: false
        schema:
          type: string
      - in: query
        name: recoverableByMe
        description: When set to true, only items that can be immediately recovered by the caller are returned.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecoverableItems'
        '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:


            * InsufficientWorkspaceRole - User doesn''t have sufficient workspace role.


            * InvalidItemType - Item type is invalid.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /workspaces/{workspaceId}/recoverableItems/{itemId}:
    delete:
      summary: Permanently deletes a recoverable item
      description: '## Permissions


        The caller must have *write* permissions for the workspace.


        ## Required Delegated Scopes


        Workspace.ReadWrite.All


        ## 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:
      - RecoverableItems
      operationId: RecoverableItems_DeleteRecoverableItem
      parameters:
      - in: path
        name: workspaceId
        description: The workspace ID.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: itemId
        description: The recoverable item ID.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Request completed successfully.
        '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:


            * InsufficientWorkspaceRole - User doesn''t have sufficient workspace role.


            * ItemNotFound - The requested item was not found.


            * InvalidTargetItemStateForSoftDeletion - The item is in invalid states for soft deletion.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /workspaces/{workspaceId}/recoverableItems/{itemId}/recover:
    post:
      summary: Recovers a soft-deleted item in the specified workspace
      description: 'Recovers a soft-deleted Fabric item to the Active provision state in the specified workspace. If the item has child items, all of them are recovered as well.


        This API supports long running operations (LRO).


        ## Permissions


        The caller must have one of the workspace roles: *Admin*, *Member* or *Contributor*.


        ## Required Delegated Scopes


        For item APIs use these scope types:

        - Generic scope: Item.ReadWrite.All

        - Specific scope: *itemType*.ReadWrite.All (for example: Notebook.ReadWrite.All)


        For more information about scopes, see scopes article.


        > [!NOTE]

        > - This operation supports partial success. If, during the recovery operation, a child item fails to be recovered, that child item and all its descendants won''t be recovered and will stay in the soft-deleted state. The other items that are not descendants of this failed child item will be recovered regardless.


        ## Microsoft Entra supported identities


        This API supports the Microsoft identities listed in this section.


        | Identity | Support |

        |-|-|

        | User | Yes |

        | Service principal and Managed identities | When the item type in the call is supported. Check the corresponding API for the item type you''re calling, to see if your call is supported. For example, semantic models are supported. |


        ## Interface'
      tags:
      - RecoverableItems
      operationId: RecoverableItems_RecoverItem
      x-ms-fabric-sdk-long-running-operation: true
      parameters:
      - in: path
        name: workspaceId
        description: The workspace ID.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: itemId
        description: The recoverable item ID.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successfully recovered the soft-deleted item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Items'
        '202':
          description: Request accepted, item recovery in progress
          headers:
            Location:
              description: The URL of the operation status which tracks the operation state.
              schema:
                type: string
            x-ms-operation-id:
              description: The operation ID 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:


            * InsufficientWorkspaceRole - User doesn''t have sufficient workspace role.


            * ItemNotFound - The requested item was not found.


            * UnsupportedCapacitySKU - The item is not supported on the current capacity of the workspace.


            * WorkspaceHasNoCapacityAssigned - The workspace has no capacity assigned.


            * ItemDisplayNameAlreadyInUse - Item display name is already in use.


            * InvalidParentItemStateForRecovery - The item''s parent item is not in Active state.


            * InvalidTargetItemStateForRecovery - The item''s state is not valid for recovery.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ItemType:
      description: The type of the item. Additional item types may be added over time.
      type: string
      enum:
      - Dashboard
      - Report
      - SemanticModel
      - PaginatedReport
      - Datamart
      - Lakehouse
      - Eventhouse
      - Environment
      - KQLDatabase
      - KQLQueryset
      - KQLDashboard
      - DataPipeline
      - Notebook
      - SparkJobDefinition
      - MLExperiment
      - MLModel
      - Warehouse
      - Eventstream
      - SQLEndpoint
      - MirroredWarehouse
      - MirroredDatabase
      - Reflex
      - GraphQLApi
      - MountedDataFactory
      - SQLDatabase
      - CopyJob
      - VariableLibrary
      - Dataflow
      - ApacheAirflowJob
      - WarehouseSnapshot
      - DigitalTwinBuilder
      - DigitalTwinBuilderFlow
      - MirroredAzureDatabricksCatalog
      - Map
      - AnomalyDetector
      - UserDataFunction
      - GraphModel
      - GraphQuerySet
      - SnowflakeDatabase
      - OperationsAgent
      - CosmosDBDatabase
      - Ontology
      - EventSchemaSet
      - DataAgent
      - MirroredCatalog
      - PolicySet
      - AppBackend
      - OrgApp
      - OrgAppAudience
      - DataBuildToolJob
      - AzureDatabricksStorage
      - Plan
      - Monitoring
      - DeploymentPlan
      x-ms-enum:
        name: ItemType
        modelAsString: true
        values:
        - value: Dashboard
          description: PowerBI dashboard.
        - value: Report
          description: PowerBI report.
        - value: SemanticModel
          description: PowerBI semantic model.
        - value: PaginatedReport
          description: PowerBI paginated report.
        - value: Datamart
          description: PowerBI datamart.
        - value: Lakehouse
          description: A lakehouse.
        - value: Eventhouse
          description: An eventhouse.
        - value: Environment
          description: An environment.
        - value: KQLDatabase
          description: A KQL database.
        - value: KQLQueryset
          description: A KQL queryset.
        - value: KQLDashboard
          description: A KQL dashboard.
        - value: DataPipeline
          description: A data pipeline.
        - value: Notebook
          description: A notebook.
        - value: SparkJobDefinition
          description: A spark job definition.
        - value: MLExperiment
          description: A machine learning experiment.
        - value: MLModel
          description: A machine learning model.
        - value: Warehouse
          description: A warehouse.
        - value: Eventstream
          description: An eventstream.
        - value: SQLEndpoint
          description: An SQL endpoint.
        - value: MirroredWarehouse
          description: A mirrored warehouse.
        - value: MirroredDatabase
          description: A mirrored database.
        - value: Reflex
          description: A Reflex.
        - value: GraphQLApi
          description: An API for GraphQL item.
        - value: MountedDataFactory
          description: A MountedDataFactory.
        - value: ApacheAirflowJob
          description: An ApacheAirflowJob.
        - value: SQLDatabase
          description: A SQLDatabase.
        - value: CopyJob
          description: A Copy job.
        - value: VariableLibrary
          description: A VariableLibrary.
        - value: MirroredAzureDatabricksCatalog
          description: A mirrored azure databricks catalog.
        - value: Dataflow
          description: A Dataflow.
        - value: WarehouseSnapshot
          description: A Warehouse snapshot.
        - value: DigitalTwinBuilder
          description: A DigitalTwinBuilder.
        - value: DigitalTwinBuilderFlow
          description: A Digital Twin Builder Flow.
        - value: AnomalyDetector
          description: An Anomaly Detector.
        - value: Map
          description: A Map.
        - value: Ontology
          description: An Ontology.
        - value: UserDataFunction
          description: A User Data Function.
        - value: GraphModel
          description: A GraphModel.
        - value: GraphQuerySet
          description: A Graph QuerySet.
        - value: SnowflakeDatabase
          description: A Snowflake Database to store Iceberg tables created from Snowflake account.
        - value: OperationsAgent
          description: A OperationsAgent.
        - value: CosmosDBDatabase
          description: A Cosmos DB Database.
        - value: EventSchemaSet
          description: An EventSchemaSet.
        - value: DataAgent
          description: A DataAgent.
        - value: MirroredCatalog
          description: A MirroredCatalog.
        - value: PolicySet
          description: A PolicySet.
        - value: AppBackend
          description: An AppBackend.
        - value: OrgApp
          description: An Org App.
        - value: OrgAppAudience
          description: An Org App Audience.
        - value: DataBuildToolJob
          description: A DataBuildToolJob.
        - value: AzureDatabricksStorage
          description: A OneLake-backed storage item for Azure Databricks.
        - value: Plan
          description: A plan.
        - value: Monitoring
          description: A Monitoring item.
        - value: DeploymentPlan
          description: A Deployment plan.
    RecoverableItem:
      description: Recoverable item.
      type: object
      required:
      - id
      - type
      - retentionExpirationDateTime
      properties:
        id:
          description: The recoverable item ID.
          type: string
          format: uuid
          readOnly: true
        displayName:
          description: The recoverable item display name.
          type: string
          readOnly: false
        description:
          description: The recoverable item description.
          type: string
          readOnly: false
        type:
          $ref: '#/components/schemas/ItemType'
        workspaceId:
          description: The workspace ID.
          type: string
          format: uuid
          readOnly: true
        parentItemId:
          description: The parent item ID of the recoverable item.
          type: string
          format: uuid
          readOnly: true
        retentionExpirationDateTime:
          description: The UTC retention expiration timestamp for the recoverable item, in ISO 8601 format (for example, '2025-12-31T23:59:59.999Z').
          type: string
          readOnly: true
        tags:
          description: List of applied tags.
          type: array
          items:
            $ref: '#/components/schemas/ItemTag'
          readOnly: true
    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
    AppliedTag:
      type: object
      description: Represents an applied tag.
      required:
      - id
      - displayName
      properties:
        id:
          type: string
          description: The tag ID.
          format: uuid
        displayName:
          type: string
          description: The name of the tag.
    RecoverableItems:
      required:
      - value
      type: object
      properties:
        value:
          description: A list of recoverable items.
          type: array
          items:
            $ref: '#/components/schemas/RecoverableItem'
      allOf:
      - $ref: '#/components/schemas/PaginatedResponse'
    SensitivityLabel:
      type: object
      description: Represents a sensitivity label applied to an item.
      required:
      - id
      properties:
        id:
          type: string
          description: The sensitivity label ID.
          format: uuid
    PrincipalType:
      description: The type of the principal. Additional principal types may be added over time.
      type: string
      enum:
      - User
      - ServicePrincipal
      - Group
      - ServicePrincipalProfile
      - EntireTenant
      x-ms-enum:
        name: PrincipalType
        modelAsString: true
        values:
        - value: User
          description: Principal is a Microsoft Entra user principal.
        - value: ServicePrincipal
          description: Principal is a Microsoft Entra service principal.
        - value: Group
          description: Principal is a security group.
        - value: ServicePrincipalProfile
          description: Principal is a service principal profile.
        - value: EntireTenant
          description: Principal represents all tenant users.
    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
    Principal:
      description: Represents an identity or a Microsoft Entra group.
      type: object
      required:
      - id
      - type
      discriminator:
        propertyName: type
      properties:
        id:
          description: The principal's ID.
          type: string
          format: uuid
          readOnly: false
        displayName:
          description: The principal's display name.
          type: string
          readOnly: true
        type:
          $ref: '#/components/schemas/PrincipalType'
    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
    Items:
      required:
      - value
      type: object
      properties:
        value:
          description: A list of items.
          type: array
          items:
            $ref: '#/components/schemas/Item'
      allOf:
      - $ref: '#/components/schemas/PaginatedResponse'
    ItemTag:
      type: object
      description: Represents a tag applied on an item.
      required:
      - id
      - displayName
      allOf:
      - $ref: '#/components/schemas/AppliedTag'
    Item:
      description: An item object.
      type: object
      required:
      - type
      properties:
        id:
          description: The item ID.
          type: string
          format: uuid
          readOnly: true
        logicalId:
          description: The item's logical identifier. Corresponding item instances share the same logical ID. The value is null when no logical ID has been assigned.
          type: string
          format: uuid
          readOnly: true
        displayName:
          description: The item display name.
          type: string
          readOnly: false
        description:
          description: The item description.
          type: string
          readOnly: false
        type:
          $ref: '#/components/schemas/ItemType'
        workspaceId:
          description: The workspace ID.
          type: string
          format: uuid
          readOnly: true
        folderId:
          description: The folder ID.
          type: string
          format: uuid
          readOnly: true
        tags:
          description: List of applied tags.
          type: array
          items:
            $ref: '#/components/schemas/ItemTag'
          readOnly: true
        defaultIdentity:
          $ref: '#/components/schemas/Principal'
        sensitivityLabel:
          $ref: '#/components/schemas/SensitivityLabel'
    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