Microsoft Fabric One Lake Settings API

openapi: 3.2.0
info:
  title: Microsoft Fabric Platform REST One Lake Settings 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: OneLakeSettings
paths:
  /workspaces/{workspaceId}/onelake/settings:
    get:
      summary: Get workspace OneLake settings
      description: '## Permissions


        The caller must have an *admin* workspace role.


        ## Required Delegated Scopes


        OneLake.Read.All or OneLake.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:
      - OneLakeSettings
      operationId: OneLakeSettings_GetSettings
      x-ms-fabric-sdk-long-running-operation: false
      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/GetOneLakeSettingsResponse'
        '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:\n\n* UnknownError - An error occurred. \n\n* WorkspaceNotFound - Workspace not found. \n\n * UserNotAuthorizedSourceWorkspace - User is not authorized for the workspace."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /workspaces/{workspaceId}/onelake/settings/modifyDiagnostics:
    post:
      summary: Enables or disables workspace OneLake diagnostic settings
      description: 'This API supports long running operations (LRO).


        ## Permissions


        * The caller must have an *admin* workspace role on the source workspace.


        * The caller must have *contributor* or above workspace role on the destination workspace.


        ## Required Delegated Scopes


        OneLake.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:
      - OneLakeSettings
      operationId: OneLakeSettings_ModifyDiagnostics
      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.
        '202':
          description: Request accepted. Modify diagnostic settings is in progress.
          headers:
            Location:
              description: The URL of the operation status. Can be used to track the operation state.
              schema:
                type: string
            x-ms-operation-id:
              description: The operation ID. 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:\n\n* UnknownError - An error occurred. \n\n* WorkspaceNotFound - Source Workspace not found. \n\n * UserNotAuthorizedSourceWorkspace - User is not authorized for the source workspace.\n\n * UserNotAuthorizedDestinationItem - User is not authorized for the destination workspace.\n\n * DestinationWorkspaceNotFound - Destination Workspace not found.\n\n * DestinationItemNotFound -Destination item not found.\n\n * WorkspaceNotInSameCapacity - Source and destination workspace not in same capacity.\n\n * SettingsNotAllowedOnWorkspace - Diagnostic setting not allowed on workspace.\n\n * RequiredDestination - Destination is required when enabling diagnostics for first time."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModifyOneLakeDiagnosticSettingRequest'
        description: The OneLake diagnostic setting object.
  /workspaces/{workspaceId}/onelake/settings/modifyImmutabilityPolicy:
    post:
      summary: Create or update OneLake immutability settings
      description: 'Set immutability policy for data stored in OneLake. Currently, this feature supports configuring a retention period specifically for diagnostic logs within a workspace, ensuring they remain unaltered once written.


        ## Permissions


        The caller must have an *admin* workspace role.


        ## Required Delegated Scopes


        OneLake.ReadWrite.All


        ## Limitations


        Can be applied only if:

        - The current workspace is storing diagnostic logs from other workspaces.

        - There is already a retention period applied to the diagnostics logs in the workspace


        ## 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:
      - OneLakeSettings
      operationId: OneLakeSettings_ModifyImmutabilityPolicy
      x-ms-fabric-sdk-long-running-operation: false
      parameters:
      - in: path
        name: workspaceId
        description: The workspace 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:


            * UserNotAuthorized - User must be an admin of the workspace to enable diagnostics settings.


            * WorkspaceNotFound - Workspace not found.


            * RetentionDaysReductionNotAllowed - Retention days cannot be reduced than what is already set.


            * WorkspaceNotSupported - Workspace is not supported for setting diagnostic immutability policy.


            * InternalServerError - Other Internal Errors.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImmutabilityPolicyRequest'
        description: The immutability policy request object.
        required: true
  /workspaces/{workspaceId}/onelake/settings/modifyDefaultTier:
    post:
      summary: Modifies the default OneLake storage tier for a workspace
      description: 'All files without an explicitly set tier will be moved to the new default tier. You will be billed for any transactions resulting from movement between tiers.


        ## Permissions


        The caller must have an *admin* workspace role.


        ## Required Delegated Scopes


        OneLake.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:
      - OneLakeSettings
      operationId: OneLakeSettings_ModifyDefaultTier
      x-ms-fabric-sdk-long-running-operation: false
      parameters:
      - in: path
        name: workspaceId
        description: The workspace ID.
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: defaultTier
        description: The new default access tier for the workspace. Additional access tier values may be added over time.
        x-ms-enum:
          name: OneLakeAccessTier
          modelAsString: true
          values:
          - value: Hot
            description: Hot access tier.
          - value: Cool
            description: Cool access tier.
          - value: Cold
            description: Cold access tier.
        required: true
        schema:
          type: string
          enum:
          - Hot
          - Cool
          - Cold
      responses:
        '200':
          description: Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModifyOneLakeWorkspaceDefaultTierResponse'
        '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.


            * EntityNotFound - Workspace not found.


            * InvalidInput - Invalid request input.


            * UserNotAuthorizedForWorkspaceLifecycle - User is not authorized for the workspace.


            * LifecycleNotAllowedForMyWorkspace - Lifecycle settings are not allowed on My Workspace.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /workspaces/{workspaceId}/onelake/settings/modifyAccessTimeTracking:
    post:
      summary: Enables or disables OneLake access time tracking for a workspace
      description: 'Enables or disables Azure Storage `LastAccessTime` tracking for OneLake files in the workspace. When enabled, file reads and writes update the file''s last access timestamp; metadata-only operations, such as checking properties, metadata, or tags, do not. Changes take effect immediately.


        ## Permissions


        The caller must have an *admin* workspace role.


        ## Required Delegated Scopes


        OneLake.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:
      - OneLakeSettings
      operationId: OneLakeSettings_ModifyAccessTimeTracking
      x-ms-fabric-sdk-long-running-operation: false
      parameters:
      - in: path
        name: workspaceId
        description: The workspace 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:


            * WorkspaceNotFound - Workspace not found.


            * UserNotAuthorized - User is not authorized. The caller must have an *admin* workspace role.


            * OneLakeNotProvisioned - The workspace has no items, so OneLake storage is not provisioned.


            * UnknownError - An error occurred.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModifyAccessTimeTrackingRequest'
        description: The modify access time tracking request object.
        required: true
components:
  schemas:
    OneLakeLifecyclePolicyStatus:
      description: The status of the OneLake lifecycle policy. Additional status values may be added over time.
      type: string
      enum:
      - Inactive
      - Active
      x-ms-enum:
        name: OneLakeLifecyclePolicyStatus
        modelAsString: true
        values:
        - value: Inactive
          description: No lifecycle policy rules are configured.
        - value: Active
          description: Lifecycle policy rules are configured and active.
    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
    ModifyAccessTimeTrackingRequest:
      description: Modify OneLake access time tracking request.
      type: object
      required:
      - status
      properties:
        status:
          $ref: '#/components/schemas/AccessTimeTrackingStatus'
    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
    AccessTimeTrackingStatus:
      description: The status of OneLake access time tracking. When enabled, Azure Storage updates the LastAccessTime property on file reads and writes. Additional status values may be added over time.
      type: string
      enum:
      - Enabled
      - Disabled
      x-ms-enum:
        name: AccessTimeTrackingStatus
        modelAsString: true
        values:
        - value: Enabled
          description: Access time tracking is enabled. Azure Storage updates LastAccessTime on file reads and writes.
        - value: Disabled
          description: Access time tracking is disabled. LastAccessTime is not updated on file access.
    ImmutabilityPolicyRequest:
      description: Immutability policy request object.
      type: object
      required:
      - scope
      - retentionDays
      properties:
        scope:
          $ref: '#/components/schemas/ImmutabilityScope'
        retentionDays:
          description: Retention Days for the action.
          type: integer
          minimum: 1
    OneLakeLifecycleSettings:
      description: OneLake lifecycle management settings.
      type: object
      required:
      - defaultTier
      - policy
      properties:
        defaultTier:
          $ref: '#/components/schemas/OneLakeAccessTier'
        policy:
          $ref: '#/components/schemas/OneLakeLifecyclePolicyStatus'
        accessTimeTracking:
          $ref: '#/components/schemas/AccessTimeTrackingStatus'
    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
    OneLakeDiagnosticSettings:
      description: OneLake diagnostic settings object.
      type: object
      required:
      - status
      properties:
        status:
          description: The status of the diagnostics settings.
          Enum:
          - Enabled
          - Disabled
          type: string
          readOnly: false
        destination:
          $ref: '#/components/schemas/OneLakeDiagnosticSettingsDestinationInfo'
    ImmutabilityScope:
      description: 'The scope of immutability policy. Additional Immutability Scope types may be added over time. '
      type: string
      enum:
      - DiagnosticLogs
      x-ms-enum:
        name: ImmutabilityScope
        modelAsString: true
        values:
        - value: DiagnosticLogs
          description: Immutability policy for diagnostic logs.
    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
    OneLakeDiagnosticSettingsDestinationInfo:
      description: The destination where OneLake diagnostic logs are stored.
      type: object
      required:
      - type
      discriminator:
        propertyName: type
      properties:
        type:
          description: The item type of the destination.
          type: string
          Enum:
          - Lakehouse
          readOnly: false
    ModifyOneLakeWorkspaceDefaultTierResponse:
      description: Response for modifying the default OneLake access tier.
      type: object
      required:
      - defaultTier
      properties:
        defaultTier:
          $ref: '#/components/schemas/OneLakeAccessTier'
    ImmutabilityPolicy:
      description: Immutability policy object.
      type: object
      required:
      - scope
      - retentionDays
      properties:
        scope:
          $ref: '#/components/schemas/ImmutabilityScope'
        retentionDays:
          description: Value of the retention days configured.
          type: integer
          minimum: 1
    ModifyOneLakeDiagnosticSettingRequest:
      $ref: '#/components/schemas/OneLakeDiagnosticSettings'
    OneLakeAccessTier:
      description: The OneLake access tier. Additional access tier values may be added over time.
      type: string
      enum:
      - Hot
      - Cool
      - Cold
      x-ms-enum:
        name: OneLakeAccessTier
        modelAsString: true
        values:
        - value: Hot
          description: Hot access tier. Highest storage costs and lowest transaction costs.
        - value: Cool
          description: Cool access tier. Lower storage costs and higher transaction costs. Minimum 30 days storage.
        - value: Cold
          description: Cold access tier. Lowest storage costs and highest transaction costs. Minimum 60 days storage.
    GetOneLakeSettingsResponse:
      description: OneLake settings response.
      type: object
      required:
      - diagnostics
      properties:
        diagnostics:
          $ref: '#/components/schemas/OneLakeDiagnosticSettings'
        immutabilityPolicies:
          description: Immutability settings of the workspace.
          type: array
          items:
            $ref: '#/components/schemas/ImmutabilityPolicy'
        lifecycle:
          description: Lifecycle management settings for the workspace. Only present when lifecycle management is enabled.
          allOf:
          - $ref: '#/components/schemas/OneLakeLifecycleSettings'