Microsoft Fabric Labels API

openapi: 3.2.0
info:
  title: Microsoft Fabric Admin REST Labels API
  version: v1
  x-source: 'https://github.com/microsoft/fabric-rest-api-specs (bundled from openapi/_original/fabric-rest-api-specs: admin/swagger.json)'
servers:
- url: https://api.fabric.microsoft.com/v1/admin
security: []
tags:
- name: Labels
paths:
  /items/bulkRemoveLabels:
    post:
      summary: Remove sensitivity labels from Fabric items (such as lakehouses and reports) by…
      description: 'For a usage example, see Set or remove sensitivity labels.


        ## Permissions


        - The user must be a Fabric Administrator.

        - The admin user must have sufficient usage rights to delete labels.


        ## Required Scope


        Tenant.ReadWrite.All


        ## Limitations


        - Maximum 25 requests per hour.

        - Each request can update up to 2,000 Fabric items.


        ## Microsoft Entra supported identities


        This API supports the Microsoft identities listed in this section.


        | Identity | Support |

        |-|-|

        | User | Yes |

        | Service principal and Managed identities | No |


        ## Interface'
      tags:
      - Labels
      operationId: Labels_BulkRemoveLabels
      responses:
        '200':
          description: Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemsChangeLabelResponse'
        '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:


            * BadRequest - Unable to process the operation due to an error in the request.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveLabelsRequest'
        description: A list of items.
        required: true
  /items/bulkSetLabels:
    post:
      summary: Set sensitivity labels on Fabric items, such as lakehouses and reports, by item…
      description: 'To set a sensitivity label using this API the admin user or the delegated user, if provided, must have the label included in their label policy. For a usage example see: Set or remove sensitivity labels.


        ## Permissions


        - The user must be a Fabric Administrator.

        - The admin user and the delegated user, if provided, must have sufficient usage rights to set labels.


        ## Required Scope


        Tenant.ReadWrite.All


        ## Limitations


        - Maximum 25 requests per hour.

        - Each request can update up to 2,000 Fabric items.


        ## Microsoft Entra supported identities


        This API supports the Microsoft identities listed in this section.


        | Identity | Support |

        |-|-|

        | User | Yes |

        | Service principal and Managed identities | No |


        ## Interface'
      tags:
      - Labels
      operationId: Labels_BulkSetLabels
      responses:
        '200':
          description: Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemsChangeLabelResponse'
        '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:


            * BadRequest - Unable to process the operation due to an error in the request.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetLabelsRequest'
        description: Set label details.
        required: true
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.
    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
    ItemInfo:
      description: The item information, including item ID and type.
      type: object
      required:
      - id
      - type
      properties:
        id:
          type: string
          description: An ID in UUID format.
          format: uuid
        type:
          $ref: '#/components/schemas/ItemType'
    SetLabelsRequest:
      description: A composite of label information required to update an information protection label.
      required:
      - items
      - labelId
      properties:
        items:
          type: array
          description: A list of items. The list includes item ID and type.
          readOnly: false
          items:
            $ref: '#/components/schemas/ItemInfo'
        labelId:
          type: string
          format: uuid
          description: The label ID, which must be in the user's label policy.
          readOnly: false
        delegatedPrincipal:
          $ref: '#/components/schemas/Principal'
        assignmentMethod:
          type: string
          description: Specifies whether the assigned label was set by an automated process or manually. Additional tenant setting property types may be added over time.
          readOnly: false
          enum:
          - Standard
          - Priviledged
          x-ms-enum:
            name: AssignmentMethod
            modelAsExtensible: true
            modelAsString: true
            values:
            - value: Standard
              description: The label was set by an automated process (default value).
            - value: Priviledged
              description: The label was set manually.
    ItemChangeLabelStatus:
      description: The unique ID and information protection label change status of a Fabric item
      required:
      - id
      - type
      - status
      properties:
        id:
          type: string
          description: The unique ID of a Fabric item. The ID is in UUID format.
          readOnly: true
        type:
          $ref: '#/components/schemas/ItemType'
        status:
          type: string
          description: The status of an information protection label change operation. Additional tenant setting property types may be added over time.
          readOnly: true
          enum:
          - Failed
          - FailedToGetUsageRights
          - InsufficientUsageRights
          - NotFound
          - Succeeded
          x-ms-enum:
            name: Status
            modelAsExtensible: true
            modelAsString: true
            values:
            - value: Failed
              description: Failed to set a new label. Please retry.
            - value: FailedToGetUsageRights
              description: Failed to set a new label. The Fabric item has a sensitivity label with protection settings, and Fabric was unable to verify that the user has sufficient usage rights to change the label.
            - value: InsufficientUsageRights
              description: Failed to set a new label. The Fabric item has a sensitivity label with protection settings, and the admin user (and the delegated user, if provided) doesn't have sufficient usage rights to change the label.
            - value: NotFound
              description: The Fabric item ID, label or type wasn't found.
            - value: Succeeded
              description: The Fabric item label was changed.
    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.
    RemoveLabelsRequest:
      description: A list of items requiring an information protection label update. Each item in the list includes the item ID and Fabric item type.
      properties:
        items:
          type: array
          description: A list of items.
          items:
            $ref: '#/components/schemas/ItemInfo'
    ItemsChangeLabelResponse:
      description: A list of the unique IDs and information protection label change status of the Fabric items in the label change request.
      properties:
        itemsChangeLabelStatus:
          type: array
          description: A list of items change label status.
          items:
            $ref: '#/components/schemas/ItemChangeLabelStatus'
    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
    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