openapi: 3.1.0
info:
  title: Azure Files FileREST API
  version: '2023-01-03'
  description: |
    Data-plane HTTPS REST API for Azure Files. Operations are scoped to the
    storage account (`https://{account-name}.file.core.windows.net`), with sub-paths
    for shares, directories, and files. Many operations select a sub-resource via the
    `?comp=` and `?restype=` query parameters (Azure Storage convention).

    Authentication: Shared Key (`SharedKey` Authorization header), Shared Access
    Signature (SAS tokens appended as query parameters), or Microsoft Entra ID
    OAuth 2.0 bearer tokens.
  contact:
    name: Azure Files FileREST API
    url: https://learn.microsoft.com/en-us/rest/api/storageservices/file-service-rest-api
servers:
  - url: https://{account-name}.file.core.windows.net
    description: Azure Files storage account endpoint
    variables:
      account-name:
        default: myaccount
        description: Storage account name
tags:
  - name: Account
    description: Account-level file service operations
  - name: Shares
    description: File share operations
  - name: Directories
    description: Directory operations within a share
  - name: Files
    description: File operations
paths:
  /:
    get:
      summary: List shares or get file service properties
      description: |
        - With `?comp=list` lists shares in the account.
        - With `?restype=service&comp=properties` returns service properties.
      operationId: listSharesOrGetServiceProperties
      tags: [Account]
      parameters:
        - { in: query, name: comp, schema: { type: string, enum: [list, properties] } }
        - { in: query, name: restype, schema: { type: string, enum: [service] } }
        - { in: query, name: prefix, schema: { type: string } }
        - { in: query, name: marker, schema: { type: string } }
        - { in: query, name: maxresults, schema: { type: integer } }
        - { in: header, name: x-ms-version, required: true, schema: { type: string, default: '2023-01-03' } }
        - { in: header, name: x-ms-date, required: true, schema: { type: string } }
      responses:
        '200':
          description: XML listing or service properties
          content:
            application/xml:
              schema: { type: string }
      security: [{ sharedKey: [] }, { entra: [] }]
  /{shareName}:
    parameters:
      - { in: path, name: shareName, required: true, schema: { type: string } }
      - { in: query, name: restype, required: true, schema: { type: string, enum: [share] } }
      - { in: header, name: x-ms-version, required: true, schema: { type: string, default: '2023-01-03' } }
      - { in: header, name: x-ms-date, required: true, schema: { type: string } }
    put:
      summary: Create a share
      operationId: createShare
      tags: [Shares]
      parameters:
        - { in: header, name: x-ms-share-quota, schema: { type: integer } }
      responses:
        '201':
          description: Share created
      security: [{ sharedKey: [] }, { entra: [] }]
    get:
      summary: Get share properties or metadata
      operationId: getShareProperties
      tags: [Shares]
      parameters:
        - { in: query, name: comp, schema: { type: string, enum: [metadata, acl, snapshot, filepermission, stats] } }
      responses:
        '200':
          description: Share properties
      security: [{ sharedKey: [] }, { entra: [] }]
    delete:
      summary: Delete a share
      operationId: deleteShare
      tags: [Shares]
      responses:
        '202': { description: Deleted }
      security: [{ sharedKey: [] }, { entra: [] }]
  /{shareName}/{directoryPath}:
    parameters:
      - { in: path, name: shareName, required: true, schema: { type: string } }
      - { in: path, name: directoryPath, required: true, schema: { type: string } }
      - { in: query, name: restype, required: true, schema: { type: string, enum: [directory] } }
      - { in: header, name: x-ms-version, required: true, schema: { type: string, default: '2023-01-03' } }
      - { in: header, name: x-ms-date, required: true, schema: { type: string } }
    put:
      summary: Create a directory
      operationId: createDirectory
      tags: [Directories]
      responses:
        '201': { description: Directory created }
      security: [{ sharedKey: [] }, { entra: [] }]
    get:
      summary: List files and directories or get directory properties
      operationId: listFilesAndDirectories
      tags: [Directories]
      parameters:
        - { in: query, name: comp, schema: { type: string, enum: [list, properties, metadata] } }
        - { in: query, name: prefix, schema: { type: string } }
        - { in: query, name: marker, schema: { type: string } }
        - { in: query, name: maxresults, schema: { type: integer } }
      responses:
        '200':
          description: Listing or properties
          content:
            application/xml:
              schema: { type: string }
      security: [{ sharedKey: [] }, { entra: [] }]
    delete:
      summary: Delete a directory
      operationId: deleteDirectory
      tags: [Directories]
      responses:
        '202': { description: Deleted }
      security: [{ sharedKey: [] }, { entra: [] }]
  /{shareName}/{filePath}:
    parameters:
      - { in: path, name: shareName, required: true, schema: { type: string } }
      - { in: path, name: filePath, required: true, schema: { type: string } }
      - { in: header, name: x-ms-version, required: true, schema: { type: string, default: '2023-01-03' } }
      - { in: header, name: x-ms-date, required: true, schema: { type: string } }
    put:
      summary: Create a file, set properties/metadata, or put a range
      description: |
        - With `x-ms-type: file` and `x-ms-content-length`, creates an empty file.
        - With `?comp=range` and `x-ms-range`/`x-ms-write` headers, writes data into a range.
        - With `?comp=properties` or `?comp=metadata`, updates the file properties/metadata.
      operationId: putFile
      tags: [Files]
      parameters:
        - { in: query, name: comp, schema: { type: string, enum: [range, properties, metadata, lease] } }
        - { in: header, name: x-ms-type, schema: { type: string, enum: [file] } }
        - { in: header, name: x-ms-content-length, schema: { type: integer } }
        - { in: header, name: x-ms-range, schema: { type: string } }
        - { in: header, name: x-ms-write, schema: { type: string, enum: [update, clear] } }
      requestBody:
        required: false
        content:
          application/octet-stream:
            schema: { type: string, format: binary }
      responses:
        '201': { description: Created }
        '200': { description: Updated }
      security: [{ sharedKey: [] }, { entra: [] }]
    get:
      summary: Download a file or get its properties
      operationId: getFile
      tags: [Files]
      parameters:
        - { in: query, name: comp, schema: { type: string, enum: [metadata, rangelist] } }
        - { in: header, name: x-ms-range, schema: { type: string } }
      responses:
        '200':
          description: File contents or properties
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        '206':
          description: Partial file contents
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
      security: [{ sharedKey: [] }, { entra: [] }]
    delete:
      summary: Delete a file
      operationId: deleteFile
      tags: [Files]
      responses:
        '202': { description: Deleted }
      security: [{ sharedKey: [] }, { entra: [] }]
    head:
      summary: Get file properties
      operationId: headFile
      tags: [Files]
      responses:
        '200': { description: Properties returned in headers }
      security: [{ sharedKey: [] }, { entra: [] }]
components:
  securitySchemes:
    sharedKey:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Shared Key authorization header in the form `SharedKey {account}:{signature}`,
        where signature is an HMAC-SHA256 of the canonicalized request.
        See https://learn.microsoft.com/en-us/rest/api/storageservices/authorize-with-shared-key
    entra:
      type: oauth2
      description: Microsoft Entra ID OAuth 2.0 bearer token
      flows:
        clientCredentials:
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes:
            https://storage.azure.com/.default: Azure Storage data plane access