Azure Files Service API

openapi: 3.2.0
info:
  title: Azure Files FileREST Service API
  version: '2026-10-06'
  description: Azure Files FileREST data-plane API (service version 2026-10-06). Converted from Microsoft's published Swagger 2.0 contract in github.com/Azure/azure-rest-api-specs (specification/storage/data-plane/FileStorage/stable/2026-10-06/file.json). Microsoft distinguishes operations by query string (x-ms-paths); path keys keep those query discriminators verbatim.
servers:
- url: https://{account-name}.file.core.windows.net
  description: Azure Files storage account endpoint (the spec templates the host as {url})
  variables:
    account-name:
      default: myaccount
      description: Storage account name
security:
- File_shared_key: []
tags:
- name: Service
paths:
  /?restype=service&comp=properties:
    parameters:
    - name: restype
      description: restype
      in: query
      required: true
      schema:
        type: string
        enum:
        - service
    - name: comp
      description: comp
      in: query
      required: true
      schema:
        type: string
        enum:
        - properties
    put:
      tags:
      - Service
      operationId: Service_SetProperties
      description: Sets properties for a storage account's File service endpoint, including properties for Storage Analytics metrics and CORS (Cross-Origin Resource Sharing) rules.
      parameters:
      - $ref: '#/components/parameters/Timeout'
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/FileRequestIntent'
      requestBody:
        required: true
        description: The StorageService properties.
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/StorageServiceProperties'
      responses:
        '202':
          description: Success (Accepted)
          headers:
            x-ms-request-id:
              description: This header uniquely identifies the request that was made and can be used for troubleshooting the request.
              schema:
                type: string
            x-ms-version:
              description: Indicates the version of the File service used to execute the request.
              schema:
                type: string
        default:
          description: Failure
          headers:
            x-ms-error-code:
              schema:
                type: string
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/StorageError'
      summary: Service set properties
      x-summary-source: derived
    get:
      tags:
      - Service
      operationId: Service_GetProperties
      description: Gets the properties of a storage account's File service, including properties for Storage Analytics metrics and CORS (Cross-Origin Resource Sharing) rules.
      parameters:
      - $ref: '#/components/parameters/Timeout'
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/FileRequestIntent'
      responses:
        '200':
          description: Success.
          headers:
            x-ms-request-id:
              description: This header uniquely identifies the request that was made and can be used for troubleshooting the request.
              schema:
                type: string
            x-ms-version:
              description: Indicates the version of the File service used to execute the request.
              schema:
                type: string
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/StorageServiceProperties'
        default:
          description: Failure
          headers:
            x-ms-error-code:
              schema:
                type: string
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/StorageError'
      summary: Service get properties
      x-summary-source: derived
  /?comp=list:
    parameters:
    - name: comp
      description: comp
      in: query
      required: true
      schema:
        type: string
        enum:
        - list
    get:
      tags:
      - Service
      operationId: Service_ListSharesSegment
      description: The List Shares Segment operation returns a list of the shares and share snapshots under the specified account.
      x-ms-pageable:
        nextLinkName: NextMarker
      parameters:
      - $ref: '#/components/parameters/Prefix'
      - $ref: '#/components/parameters/Marker'
      - $ref: '#/components/parameters/MaxResults'
      - $ref: '#/components/parameters/ListSharesInclude'
      - $ref: '#/components/parameters/Timeout'
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/FileRequestIntent'
      responses:
        '200':
          description: Success.
          headers:
            x-ms-request-id:
              description: This header uniquely identifies the request that was made and can be used for troubleshooting the request.
              schema:
                type: string
            x-ms-version:
              description: Indicates the version of the File service used to execute the request.
              schema:
                type: string
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ListSharesResponse'
        default:
          description: Failure
          headers:
            x-ms-error-code:
              schema:
                type: string
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/StorageError'
      summary: Service list shares segment
      x-summary-source: derived
  /?restype=service&comp=userdelegationkey:
    parameters:
    - name: restype
      description: restype
      in: query
      required: true
      schema:
        type: string
        enum:
        - service
    - name: comp
      description: comp
      in: query
      required: true
      schema:
        type: string
        enum:
        - userdelegationkey
    post:
      tags:
      - Service
      operationId: Service_GetUserDelegationKey
      description: Retrieves a user delegation key for the File service. This is only a valid operation when using bearer token authentication.
      parameters:
      - $ref: '#/components/parameters/Timeout'
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/ClientRequestId'
      requestBody:
        required: true
        description: Key information
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/KeyInfo'
      responses:
        '200':
          description: Success.
          headers:
            x-ms-client-request-id:
              description: If a client request id header is sent in the request, this header will be present in the response with the same value.
              schema:
                type: string
            x-ms-request-id:
              description: This header uniquely identifies the request that was made and can be used for troubleshooting the request.
              schema:
                type: string
            x-ms-version:
              description: Indicates the version of the Blob service used to execute the request. This header is returned for requests made against version 2009-09-19 and above.
              schema:
                type: string
            Date:
              description: UTC date/time value generated by the service that indicates the time at which the response was initiated
              schema:
                type: string
                format: date-time-rfc1123
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/UserDelegationKey'
        default:
          description: Failure
          headers:
            x-ms-error-code:
              schema:
                type: string
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/StorageError'
      summary: Service get user delegation key
      x-summary-source: derived
components:
  schemas:
    ShareItemInternal:
      xml:
        name: Share
      description: A listed Azure Storage share item.
      type: object
      required:
      - Name
      - Properties
      properties:
        Name:
          type: string
        Snapshot:
          type: string
        Deleted:
          type: boolean
        Version:
          type: string
        Properties:
          $ref: '#/components/schemas/SharePropertiesInternal'
        Metadata:
          $ref: '#/components/schemas/Metadata'
    Metadata:
      type: object
      additionalProperties:
        type: string
    LeaseStatus:
      xml:
        name: LeaseStatus
      description: The current lease status of the share.
      type: string
      enum:
      - locked
      - unlocked
      x-ms-enum:
        name: LeaseStatusType
        modelAsString: false
    LeaseState:
      xml:
        name: LeaseState
      description: Lease state of the share.
      type: string
      enum:
      - available
      - leased
      - expired
      - breaking
      - broken
      x-ms-enum:
        name: LeaseStateType
        modelAsString: false
    StorageServiceProperties:
      description: Storage service properties.
      type: object
      properties:
        HourMetrics:
          description: A summary of request statistics grouped by API in hourly aggregates for files.
          $ref: '#/components/schemas/Metrics'
        MinuteMetrics:
          description: A summary of request statistics grouped by API in minute aggregates for files.
          $ref: '#/components/schemas/Metrics'
        Cors:
          description: The set of CORS rules.
          type: array
          items:
            $ref: '#/components/schemas/CorsRule'
          xml:
            wrapped: true
        Protocol:
          description: Protocol settings
          $ref: '#/components/schemas/ShareProtocolSettings'
    SmbMultichannel:
      description: Settings for SMB multichannel
      type: object
      properties:
        Enabled:
          type: boolean
          description: If SMB multichannel is enabled.
      xml:
        name: Multichannel
    ShareNfsSettings:
      description: Settings for SMB protocol.
      type: object
      xml:
        name: NFS
      properties:
        EncryptionInTransit:
          description: Enable or disable encryption in transit.
          type: object
          properties:
            Required:
              description: If encryption in transit is required
              type: boolean
    ShareRootSquash:
      type: string
      enum:
      - NoRootSquash
      - RootSquash
      - AllSquash
      x-ms-enum:
        name: ShareRootSquash
        modelAsString: false
    KeyInfo:
      type: object
      required:
      - Expiry
      description: Key information
      properties:
        Start:
          description: The date-time the key is active in ISO 8601 UTC time
          type: string
        Expiry:
          description: The date-time the key expires in ISO 8601 UTC time
          type: string
        DelegatedUserTid:
          description: The delegated user tenant id in Azure AD
          type: string
    ListSharesResponse:
      xml:
        name: EnumerationResults
      description: An enumeration of shares.
      type: object
      required:
      - ServiceEndpoint
      - NextMarker
      properties:
        ServiceEndpoint:
          type: string
          xml:
            attribute: true
        Prefix:
          type: string
        Marker:
          type: string
        MaxResults:
          type: integer
        ShareItems:
          type: array
          items:
            $ref: '#/components/schemas/ShareItemInternal'
          xml:
            name: Shares
            wrapped: true
        NextMarker:
          type: string
    UserDelegationKey:
      type: object
      required:
      - SignedOid
      - SignedTid
      - SignedStart
      - SignedExpiry
      - SignedService
      - SignedVersion
      - Value
      description: A user delegation key
      properties:
        SignedOid:
          description: The Azure Active Directory object ID in GUID format.
          type: string
        SignedTid:
          description: The Azure Active Directory tenant ID in GUID format
          type: string
        SignedStart:
          description: The date-time the key is active
          type: string
          format: date-time
        SignedExpiry:
          description: The date-time the key expires
          type: string
          format: date-time
        SignedService:
          description: Abbreviation of the Azure Storage service that accepts the key
          type: string
        SignedVersion:
          description: The service version that created the key
          type: string
        SignedDelegatedUserTid:
          description: The delegated user tenant id in Azure AD. Return if DelegatedUserTid is specified.
          type: string
        Value:
          description: The key as a base64 string
          type: string
    CorsRule:
      description: CORS is an HTTP feature that enables a web application running under one domain to access resources in another domain. Web browsers implement a security restriction known as same-origin policy that prevents a web page from calling APIs in a different domain; CORS provides a secure way to allow one domain (the origin domain) to call APIs in another domain.
      type: object
      required:
      - AllowedOrigins
      - AllowedMethods
      - AllowedHeaders
      - ExposedHeaders
      - MaxAgeInSeconds
      properties:
        AllowedOrigins:
          description: The origin domains that are permitted to make a request against the storage service via CORS. The origin domain is the domain from which the request originates. Note that the origin must be an exact case-sensitive match with the origin that the user age sends to the service. You can also use the wildcard character '*' to allow all origin domains to make requests via CORS.
          type: string
        AllowedMethods:
          description: The methods (HTTP request verbs) that the origin domain may use for a CORS request. (comma separated)
          type: string
        AllowedHeaders:
          description: The request headers that the origin domain may specify on the CORS request.
          type: string
        ExposedHeaders:
          description: The response headers that may be sent in the response to the CORS request and exposed by the browser to the request issuer.
          type: string
        MaxAgeInSeconds:
          description: The maximum amount time that a browser should cache the preflight OPTIONS request.
          type: integer
          minimum: 0
    ShareEnabledProtocols:
      type: string
    ShareProtocolSettings:
      description: Protocol settings
      type: object
      xml:
        name: ProtocolSettings
      properties:
        Smb:
          description: Settings for SMB protocol.
          $ref: '#/components/schemas/ShareSmbSettings'
        Nfs:
          description: Settings for NFS protocol.
          $ref: '#/components/schemas/ShareNfsSettings'
    Metrics:
      description: Storage Analytics metrics for file service.
      required:
      - Version
      - Enabled
      properties:
        Version:
          description: The version of Storage Analytics to configure.
          type: string
        Enabled:
          description: Indicates whether metrics are enabled for the File service.
          type: boolean
        IncludeAPIs:
          description: Indicates whether metrics should generate summary statistics for called API operations.
          type: boolean
        RetentionPolicy:
          $ref: '#/components/schemas/RetentionPolicy'
    ShareSmbSettings:
      description: Settings for SMB protocol.
      type: object
      xml:
        name: SMB
      properties:
        Multichannel:
          description: Settings for SMB Multichannel.
          $ref: '#/components/schemas/SmbMultichannel'
        EncryptionInTransit:
          description: Enable or disable encryption in transit.
          type: object
          properties:
            Required:
              description: If encryption in transit is required
              type: boolean
    SharePropertiesInternal:
      description: Properties of a share.
      type: object
      required:
      - Last-Modified
      - Etag
      - Quota
      properties:
        Last-Modified:
          type: string
          format: date-time-rfc1123
        Etag:
          type: string
        Quota:
          type: integer
        ProvisionedIops:
          type: integer
        ProvisionedIngressMBps:
          type: integer
        ProvisionedEgressMBps:
          type: integer
        ProvisionedBandwidthMiBps:
          type: integer
        NextAllowedQuotaDowngradeTime:
          type: string
          format: date-time-rfc1123
        DeletedTime:
          type: string
          format: date-time-rfc1123
        RemainingRetentionDays:
          type: integer
        AccessTier:
          type: string
        AccessTierChangeTime:
          type: string
          format: date-time-rfc1123
        AccessTierTransitionState:
          type: string
        LeaseStatus:
          $ref: '#/components/schemas/LeaseStatus'
        LeaseState:
          $ref: '#/components/schemas/LeaseState'
        LeaseDuration:
          $ref: '#/components/schemas/LeaseDuration'
        EnabledProtocols:
          $ref: '#/components/schemas/ShareEnabledProtocols'
        RootSquash:
          $ref: '#/components/schemas/ShareRootSquash'
        EnableSnapshotVirtualDirectoryAccess:
          type: boolean
        PaidBurstingEnabled:
          type: boolean
        PaidBurstingMaxIops:
          type: integer
          format: int64
        PaidBurstingMaxBandwidthMibps:
          type: integer
          format: int64
        IncludedBurstIops:
          type: integer
          format: int64
        MaxBurstCreditsForIops:
          type: integer
          format: int64
        NextAllowedProvisionedIopsDowngradeTime:
          type: string
          format: date-time-rfc1123
        NextAllowedProvisionedBandwidthDowngradeTime:
          type: string
          format: date-time-rfc1123
        EnableSmbDirectoryLease:
          type: boolean
    LeaseDuration:
      xml:
        name: LeaseDuration
      description: When a share is leased, specifies whether the lease is of infinite or fixed duration.
      type: string
      enum:
      - infinite
      - fixed
      x-ms-enum:
        name: LeaseDurationType
        modelAsString: false
    StorageError:
      type: object
      properties:
        Message:
          type: string
        CopySourceStatusCode:
          type: integer
          format: int64
        CopySourceErrorCode:
          type: string
        CopySourceErrorMessage:
          type: string
        AuthenticationErrorDetail:
          type: string
    RetentionPolicy:
      description: The retention policy.
      type: object
      required:
      - Enabled
      properties:
        Enabled:
          description: Indicates whether a retention policy is enabled for the File service. If false, metrics data is retained, and the user is responsible for deleting it.
          type: boolean
        Days:
          description: Indicates the number of days that metrics data should be retained. All data older than this value will be deleted. Metrics data is deleted on a best-effort basis after the retention period expires.
          type: integer
          minimum: 1
          maximum: 365
  parameters:
    ClientRequestId:
      name: x-ms-client-request-id
      x-ms-client-name: requestId
      in: header
      required: false
      x-ms-parameter-location: method
      description: Provides a client-generated, opaque value with a 1 KB character limit that is recorded in the analytics logs when storage analytics logging is enabled.
      schema:
        type: string
    MaxResults:
      name: maxresults
      in: query
      description: Specifies the maximum number of entries to return. If the request does not specify maxresults, or specifies a value greater than 5,000, the server will return up to 5,000 items.
      required: false
      x-ms-parameter-location: method
      schema:
        type: integer
        minimum: 1
    Prefix:
      name: prefix
      in: query
      description: Filters the results to return only entries whose name begins with the specified prefix.
      required: false
      x-ms-parameter-location: method
      schema:
        type: string
    FileRequestIntent:
      name: x-ms-file-request-intent
      x-ms-client-name: fileRequestIntent
      in: header
      description: Valid value is backup
      required: false
      schema:
        type: string
        enum:
        - backup
        x-ms-enum:
          name: ShareTokenIntent
          modelAsString: true
    ListSharesInclude:
      name: include
      in: query
      description: Include this parameter to specify one or more datasets to include in the response.
      required: false
      x-ms-parameter-location: method
      schema:
        type: array
        items:
          type: string
          enum:
          - snapshots
          - metadata
          - deleted
          x-ms-enum:
            name: ListSharesIncludeType
            modelAsString: false
    Marker:
      name: marker
      in: query
      description: A string value that identifies the portion of the list to be returned with the next list operation. The operation returns a marker value within the response body if the list returned was not complete. The marker value may then be used in a subsequent call to request the next set of list items. The marker value is opaque to the client.
      required: false
      x-ms-parameter-location: method
      schema:
        type: string
    Timeout:
      name: timeout
      in: query
      description: The timeout parameter is expressed in seconds. For more information, see <a href="https://learn.microsoft.com/rest/api/storageservices/Setting-Timeouts-for-File-Service-Operations">Setting Timeouts for File Service Operations.</a>
      required: false
      x-ms-parameter-location: method
      schema:
        type: integer
        minimum: 0
    ApiVersionParameter:
      name: x-ms-version
      x-ms-client-name: version
      x-ms-parameter-location: client
      in: header
      description: Specifies the version of the operation to use for this request.
      required: true
      schema:
        type: string
  securitySchemes:
    File_shared_key:
      type: apiKey
      name: Authorization
      in: header
x-source: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/storage/data-plane/FileStorage/stable/2026-10-06/file.json
x-converted-from: swagger 2.0 x-ms-paths, mechanically