Microsoft Fabric Workloads API

openapi: 3.2.0
info:
  title: Microsoft Fabric Admin REST Workloads 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: Workloads
paths:
  /workloads:
    get:
      summary: Returns all workloads, optionally filtered by assignment status.
      description: 'This API supports pagination.


        Note: Only published workloads are visible.


        ## Permissions


        The caller must be a Fabric administrator or authenticate using a service principal.


        ## Required Delegated Scopes


        Tenant.Read.All or Tenant.ReadWrite.All


        ## Limitations


        Maximum 200 requests per hour.


        ## 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:
      - Workloads
      operationId: Workloads_ListWorkloads
      x-ms-pageable:
        nextLinkName: continuationUri
        itemName: value
      parameters:
      - in: query
        name: assignmentStatus
        description: Assignment status of workloads. Additional assignment statuses may be added over time.
        x-ms-enum:
          name: WorkloadAssignmentStatus
          modelAsString: true
          values:
          - value: Any
            description: Workloads that are assigned or unassigned.
          - value: Assigned
            description: Workloads that are assigned to the tenant or to at least one workspace or capacity in the tenant.
          - value: Unassigned
            description: Workloads that are not assigned to the tenant, any workspace, or any capacity in the tenant.
        required: false
        schema:
          type: string
          enum:
          - Any
          - Assigned
          - Unassigned
          default: Any
      - in: query
        name: continuationToken
        description: Continuation token. Used to get the next items in the list.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK. The operation was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkloadAssignmentInfos'
        '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 - Invalid query parameters.


            * PrivateLinksUnsupported - The API is not supported with Private Links enabled.


            * Unauthorized - The caller doesn''t have permission to call the API.


            * TooManyRequests - The caller has exceeded the number of requests allowed in the current time frame and further requests will fail.


            * InternalServerError - Unexpected server error.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /workloads/assignments:
    get:
      summary: List all workload assignments.
      description: 'This API supports pagination.


        Note: Only published workloads are visible.


        ## Permissions


        The caller must be a Fabric administrator or authenticate using a service principal.


        ## Required Delegated Scopes


        Tenant.Read.All or Tenant.ReadWrite.All


        ## Limitations


        Maximum 200 requests per hour.


        ## 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:
      - Workloads
      operationId: Workloads_ListWorkloadAssignments
      x-ms-pageable:
        nextLinkName: continuationUri
        itemName: value
      parameters:
      - in: query
        name: continuationToken
        description: Continuation token. Used to get the next items in the list.
        required: false
        schema:
          type: string
      - in: query
        name: Type
        description: Assignment type. Additional assignment types may be added over time.
        required: false
        x-ms-enum:
          name: WorkloadAssignmentType
          modelAsString: true
          values:
          - value: Capacity
            description: Capacity assignment type.
          - value: Workspace
            description: Workspace assignment type.
          - value: Tenant
            description: Tenant assignment type.
        schema:
          type: string
          enum:
          - Capacity
          - Workspace
          - Tenant
      - in: query
        name: workloadId
        description: WorkloadID filter.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK. The operation was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkloadAssignments'
        '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:


            * WorkloadNotFound - Provided workload ID can''t be found.


            * PrivateLinksUnsupported - The API is not supported with Private Links enabled.


            * Unauthorized - The caller doesn''t have permission to call the API.


            * TooManyRequests - The caller has exceeded the number of requests allowed in the current time frame and further requests will fail.


            * InternalServerError - Unexpected server error.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      summary: Create workload assignment
      description: '## Permissions


        The caller must be a Fabric administrator or authenticate using a service principal.


        ## Required Delegated Scopes


        Tenant.ReadWrite.All


        ## Limitations


        Maximum 200 requests per hour.


        ## 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:
      - Workloads
      operationId: Workloads_CreateWorkloadAssignment
      responses:
        '201':
          description: Created. Workload assignment created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseWorkloadAssignment'
        '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:


            * WorkloadNotFound - Provided workload ID can''t be found.


            * PrivateLinksUnsupported - The API is not supported with Private Links enabled.


            * Unauthorized - The caller doesn''t have permission to call the API.


            * TooManyRequests - The caller has exceeded the number of requests allowed in the current time frame and further requests will fail.


            * InternalServerError - Unexpected server error.


            * BadRequest - Invalid request type, Missing capacity/workspace IDs in request body, Invalid capacity/workspace ID received.


            * CapacityNotFound - Capacity not found in the tenant.


            * WorkspaceNotFound - Workspace not found in the tenant.


            * WorkspaceHaveNoCapacity - Workspace have no capacity assigned.


            * WorkspaceHaveUnsupportedSKU - Workspace have unsupported capacity SKU tier.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkloadBaseAssignmentRequest'
        description: The request payload for creating workload assignment.
        required: true
  /workloads/assignments/{assignmentId}:
    delete:
      summary: Delete workload assignment
      description: '## Permissions


        The caller must be a Fabric administrator or authenticate using a service principal.


        ## Required Delegated Scopes


        Tenant.ReadWrite.All


        ## Limitations


        Maximum 200 requests per hour.


        ## 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:
      - Workloads
      operationId: Workloads_DeleteWorkloadAssignment
      parameters:
      - in: path
        name: assignmentId
        description: Assignment ID.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK. Assignment deleted 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:


            * AssignmentNotFound - Provided assignment ID can''t be found.


            * PrivateLinksUnsupported - The API is not supported with Private Links enabled.


            * Unauthorized - The caller doesn''t have permission to call the API.


            * TooManyRequests - The caller has exceeded the number of requests allowed in the current time frame and further requests will fail.


            * InternalServerError - Unexpected server error.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    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
    BaseWorkloadAssignment:
      required:
      - id
      - type
      - workloadId
      description: Base workload assignment.
      type: object
      discriminator:
        propertyName: type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the assignment.
          readOnly: true
        type:
          $ref: '#/components/schemas/WorkloadAssignmentType'
        workloadId:
          type: string
          description: The unique identifier of the workload.
          readOnly: true
    WorkloadAssignmentInfo:
      required:
      - id
      - name
      - publisher
      - isAssignable
      - isAssignedToTenant
      - assignedCapacitiesCount
      - assignedWorkspacesCount
      description: Workload assignment information. Contains details about a workload and its assignment status across the tenant, capacities, and workspaces.
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the workload.
          readOnly: true
        name:
          type: string
          description: The display name of the workload.
          readOnly: true
        publisher:
          type: string
          description: The publisher of the workload.
          readOnly: true
        isAssignable:
          type: boolean
          description: Specifies if the workload is assignable. When true, the workload can be assigned to tenant, capacities or workspaces.
          readOnly: true
        isAssignedToTenant:
          type: boolean
          description: Specifies if the workload is assigned to the tenant scope. When true, the workload is available across the entire tenant.
          readOnly: true
        assignedCapacitiesCount:
          type: integer
          description: The number of capacities to which the workload has been assigned.
          readOnly: true
        assignedWorkspacesCount:
          type: integer
          description: The number of workspaces to which the workload has been assigned.
          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
    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
    WorkloadAssignmentType:
      type: string
      description: The type of workload assignment. Specifies whether a workload is assigned to a capacity, workspace, or tenant. Additional assignment types may be added over time.
      enum:
      - Capacity
      - Workspace
      - Tenant
      x-ms-enum:
        name: WorkloadAssignmentType
        modelAsString: true
        values:
        - value: Capacity
          description: Capacity assignment type. The workload is assigned to a specific capacity.
        - value: Workspace
          description: Workspace assignment type. The workload is assigned to a specific workspace.
        - value: Tenant
          description: Tenant assignment type. The workload is assigned to the entire tenant scope.
    WorkloadAssignmentInfos:
      description: A paginated list of workloads in the tenant. Contains workload information with assignment status details.
      type: object
      properties:
        value:
          type: array
          description: The list of workloads with their assignment information.
          items:
            $ref: '#/components/schemas/WorkloadAssignmentInfo'
      allOf:
      - $ref: '#/components/schemas/PaginatedResponse'
    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.
    CreateWorkloadBaseAssignmentRequest:
      required:
      - type
      - workloadId
      description: Base request for creating workload assignments.
      type: object
      discriminator:
        propertyName: type
      properties:
        type:
          $ref: '#/components/schemas/WorkloadAssignmentType'
        workloadId:
          type: string
          description: The unique identifier of the workload to assign.
    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
    WorkloadAssignments:
      description: A paginated list of workload assignments. Contains assignments for workloads to capacities, workspaces, or tenant.
      type: object
      properties:
        value:
          type: array
          description: The list of workload assignments. Each item can be a Capacity, Workspace, or Tenant assignment.
          items:
            $ref: '#/components/schemas/BaseWorkloadAssignment'
      allOf:
      - $ref: '#/components/schemas/PaginatedResponse'