Microsoft Fabric Workspace Settings API

openapi: 3.2.0
info:
  title: Microsoft Fabric Workload Items REST Workspace Settings 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: WorkspaceSettings
paths:
  /workspaces/{workspaceId}/apacheAirflowJobs/settings?beta=true:
    get:
      tags:
      - WorkspaceSettings
      summary: Get Apache Airflow workspace settings
      description: '> [!NOTE]

        > This API is part of a Beta release and is provided for evaluation and development purposes only. It may change based on feedback and is not recommended for production use.


        ## Permissions


        The caller must have *viewer* or higher workspace role.


        ## Required Delegated Scopes


        Workspace.Read.All or Workspace.ReadWrite.All


        **When calling this API, callers must specify `true` as the value for the query parameter `beta`.**


        ## 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'
      operationId: WorkspaceSettings_Get_Airflow_Workspace_Settings_(beta)
      parameters:
      - name: workspaceId
        in: path
        description: The workspace ID.
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: beta
        description: This required parameter must be set to `true` to access this API, which is currently in beta.
        required: true
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AirflowWorkspaceSettings'
        '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:


            * UnknownError - An error occurred.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags:
      - WorkspaceSettings
      summary: Update Apache Airflow workspace settings
      description: '> [!NOTE]

        > This API is part of a Beta release and is provided for evaluation and development purposes only. It may change based on feedback and is not recommended for production use.


        ## Permissions


        The caller must have *admin* workspace role.


        ## Required Delegated Scopes


        Workspace.ReadWrite.All


        **When calling this API, callers must specify `true` as the value for the query parameter `beta`.**


        ## 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'
      operationId: WorkspaceSettings_Update_Airflow_Workspace_Settings_(beta)
      parameters:
      - name: workspaceId
        in: path
        description: The workspace ID.
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: beta
        description: This required parameter must be set to `true` to access this API, which is currently in beta.
        required: true
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AirflowWorkspaceSettings'
        '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:


            * UnknownError - An error occurred.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAirflowWorkspaceSettingsRequest'
        description: Update Apache Airflow workspace settings request payload.
        required: true
  /workspaces/{workspaceId}/spark/settings:
    get:
      tags:
      - WorkspaceSettings
      summary: Get workspace spark settings
      description: '## Permissions


        The caller must have *viewer* or higher 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'
      operationId: WorkspaceSettings_GetSparkSettings
      parameters:
      - name: workspaceId
        in: path
        description: The workspace ID.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceSparkSettings'
        '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:


            * UnknownError - An error occurred.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags:
      - WorkspaceSettings
      summary: Update workspace spark settings
      description: '## Permissions


        The caller must have *admin* workspace role.


        ## 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'
      operationId: WorkspaceSettings_UpdateSparkSettings
      parameters:
      - name: workspaceId
        in: path
        description: The workspace ID.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceSparkSettings'
        '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:


            * UnknownError - An error occurred.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkspaceSparkSettingsRequest'
        description: Update workspace Spark settings request payload.
        required: true
components:
  schemas:
    AutomaticLogProperties:
      description: Automatic Log Properties.
      required:
      - enabled
      type: object
      properties:
        enabled:
          type: boolean
          description: The status of the automatic log. False - Disabled, true - Enabled.
    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
    UpdateWorkspaceSparkSettingsRequest:
      type: object
      description: Update workspace Spark settings request payload.
      properties:
        automaticLog:
          $ref: '#/components/schemas/AutomaticLogProperties'
        highConcurrency:
          $ref: '#/components/schemas/HighConcurrencyProperties'
        pool:
          $ref: '#/components/schemas/PoolProperties'
        environment:
          $ref: '#/components/schemas/spark_EnvironmentProperties'
        job:
          $ref: '#/components/schemas/SparkJobsProperties'
    PoolProperties:
      type: object
      description: Properties of a pool
      properties:
        customizeComputeEnabled:
          description: Customize compute configurations for items. False - Disabled, true - Enabled.
          type: boolean
        defaultPool:
          $ref: '#/components/schemas/InstancePool'
        starterPool:
          $ref: '#/components/schemas/StarterPoolProperties'
    HighConcurrencyProperties:
      description: High Concurrency Properties.
      type: object
      properties:
        notebookInteractiveRunEnabled:
          type: boolean
          description: The status of the high concurrency for notebook interactive run. False - Disabled, true - Enabled.
        notebookPipelineRunEnabled:
          type: boolean
          description: The status of the high concurrency for notebook pipeline run. False - Disabled, true - Enabled.
    SparkJobsProperties:
      description: Properties of a Spark job.
      type: object
      properties:
        conservativeJobAdmissionEnabled:
          description: Reserve maximum cores for active Spark jobs. When this setting is enabled, your Fabric capacity reserves the maximum number of cores needed for active Spark jobs, ensuring job reliability by making sure that cores are available if a job scales up. When this setting is disabled, jobs are started based on the minimum number of cores needed, letting more jobs run at the same time. For more information see [job admission and management](/fabric/data-engineering/job-admission-management). False - Disabled, true - Enabled.
          type: boolean
        sessionTimeoutInMinutes:
          description: Time to terminate inactive Spark sessions. The maximum is 14 days.
          format: int32
          type: integer
          minimum: 1
          maximum: 20160
    StarterPoolProperties:
      description: Custom starter pool.
      type: object
      properties:
        maxNodeCount:
          format: int32
          description: The maximum node count.
          type: integer
          minimum: 1
        maxExecutors:
          format: int32
          description: The maximum executors count.
          type: integer
          minimum: 1
    AirflowWorkspaceSettings:
      type: object
      description: Apache Airflow workspace settings.
      properties:
        defaultPoolTemplateId:
          type: string
          format: uuid
          description: The default pool template ID for the workspace.
    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
    UpdateAirflowWorkspaceSettingsRequest:
      type: object
      description: Update Apache Airflow workspace settings request payload.
      properties:
        defaultPoolTemplateId:
          type: string
          format: uuid
          description: The default pool template ID for the workspace.
    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
    spark_EnvironmentProperties:
      description: Properties of an environment.
      type: object
      properties:
        name:
          description: The name of the default environment. Empty string indicated there is no workspace default environment.
          type: string
        runtimeVersion:
          description: '[Runtime](/fabric/data-engineering/runtime) version. For example: 1.3'
          type: string
    CustomPoolType:
      type: string
      description: Custom pool type. Additional `CustomPoolType` types may be added over time.
      enum:
      - Workspace
      - Capacity
      x-ms-enum:
        name: CustomPoolType
        modelAsString: true
        values:
        - value: Workspace
          description: Workspace level custom pool
        - value: Capacity
          description: Capacity level custom pool
    WorkspaceSparkSettings:
      type: object
      description: Workspace Spark settings.
      properties:
        automaticLog:
          $ref: '#/components/schemas/AutomaticLogProperties'
        highConcurrency:
          $ref: '#/components/schemas/HighConcurrencyProperties'
        pool:
          $ref: '#/components/schemas/PoolProperties'
        environment:
          $ref: '#/components/schemas/spark_EnvironmentProperties'
        job:
          $ref: '#/components/schemas/SparkJobsProperties'
    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
    InstancePool:
      type: object
      description: The instance pool.
      properties:
        name:
          description: Instance pool name.
          type: string
        type:
          $ref: '#/components/schemas/CustomPoolType'
        id:
          format: uuid
          description: Instance pool ID.
          type: string
        maxClustersToHydrateLimit:
          description: Server-computed upper bound for the live pool `maxClustersToHydrate` setting, determined by the capacity size associated with this pool.
          format: int32
          type: integer
          readOnly: true