Azure Blob Storage Blobs API

openapi: 3.1.0
info:
  title: Azure Blob Storage REST Append Blobs API
  description: The Azure Blob Storage REST API provides programmatic access to unstructured data storage in Azure. It supports operations on the Blob service, containers, and blobs, including block blobs, append blobs, and page blobs. Blobs can store any type of text or binary data such as documents, media files, and application installers. Blob Storage is optimized for storing massive amounts of unstructured data accessible via HTTP or HTTPS from anywhere in the world.
  version: '2024-11-04'
  contact:
    name: Microsoft Azure Support
    url: https://azure.microsoft.com/en-us/support/
  termsOfService: https://azure.microsoft.com/en-us/support/legal/
servers:
- url: https://{accountName}.blob.core.windows.net
  description: Azure Blob Storage endpoint
  variables:
    accountName:
      description: The name of the Azure Storage account
      default: mystorageaccount
security:
- sharedKey: []
- bearerAuth: []
- sharedAccessSignature: []
tags:
- name: Blobs
  description: Operations on blobs including get, put, delete, and metadata
paths:
  /{container}/{blob}:
    put:
      operationId: putBlob
      summary: Azure Blob Storage Put blob
      description: Creates a new blob or replaces an existing blob within a container. The type of blob to create is specified in the x-ms-blob-type header. For block blobs up to 5000 MiB, the entire content can be uploaded in a single request.
      tags:
      - Blobs
      parameters:
      - $ref: '#/components/parameters/ContainerName'
      - $ref: '#/components/parameters/BlobName'
      - $ref: '#/components/parameters/ApiVersion'
      - name: x-ms-blob-type
        in: header
        required: true
        description: The type of blob to create.
        schema:
          type: string
          enum:
          - BlockBlob
          - PageBlob
          - AppendBlob
      - name: Content-Length
        in: header
        description: The length of the request body in bytes. Required for page blobs (set to 0 with x-ms-blob-content-length for the actual size).
        schema:
          type: integer
      - name: Content-Type
        in: header
        description: The MIME content type of the blob.
        schema:
          type: string
      - name: x-ms-blob-content-type
        in: header
        description: The content type to set for the blob.
        schema:
          type: string
      - name: x-ms-access-tier
        in: header
        description: The tier to set on the blob.
        schema:
          type: string
          enum:
          - Hot
          - Cool
          - Cold
          - Archive
      - name: x-ms-blob-content-length
        in: header
        description: Required for page blobs. Specifies the maximum size for the page blob, up to 8 TiB. Must be aligned to a 512-byte boundary.
        schema:
          type: integer
          format: int64
      requestBody:
        description: The blob content. Not applicable for page blobs where content is uploaded through Put Page operations.
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '201':
          description: Blob created or replaced successfully
        '409':
          description: Conflict - blob exists and has an active lease
    get:
      operationId: getBlob
      summary: Azure Blob Storage Get blob
      description: Reads or downloads a blob from Blob Storage, including its user-defined metadata and system properties. A range of bytes can be requested using the Range header.
      tags:
      - Blobs
      parameters:
      - $ref: '#/components/parameters/ContainerName'
      - $ref: '#/components/parameters/BlobName'
      - $ref: '#/components/parameters/ApiVersion'
      - name: Range
        in: header
        description: Return only the bytes of the blob in the specified range, for example bytes=0-1023.
        schema:
          type: string
      - name: snapshot
        in: query
        description: The snapshot identifier. When specified, the operation returns the snapshot of the blob.
        schema:
          type: string
      - name: versionid
        in: query
        description: The version ID. When specified, the operation returns the specified version of the blob.
        schema:
          type: string
      responses:
        '200':
          description: Blob content returned
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '206':
          description: Partial blob content returned for range request
        '404':
          description: Blob not found
    head:
      operationId: getBlobProperties
      summary: Azure Blob Storage Get blob properties
      description: Returns all system properties and user-defined metadata on the blob. Does not return the blob content. Properties are returned as response headers.
      tags:
      - Blobs
      parameters:
      - $ref: '#/components/parameters/ContainerName'
      - $ref: '#/components/parameters/BlobName'
      - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Blob properties returned in response headers
        '404':
          description: Blob not found
    delete:
      operationId: deleteBlob
      summary: Azure Blob Storage Delete blob
      description: Marks the specified blob or snapshot for deletion. The blob is later deleted during garbage collection. If soft delete is enabled, the blob can be restored within the retention period.
      tags:
      - Blobs
      parameters:
      - $ref: '#/components/parameters/ContainerName'
      - $ref: '#/components/parameters/BlobName'
      - $ref: '#/components/parameters/ApiVersion'
      - name: x-ms-delete-snapshots
        in: header
        description: Required if the blob has associated snapshots. Specifies whether to delete the blob and all snapshots (include) or only the snapshots (only).
        schema:
          type: string
          enum:
          - include
          - only
      - name: snapshot
        in: query
        description: The snapshot identifier. When specified, only the snapshot is deleted.
        schema:
          type: string
      responses:
        '202':
          description: Blob marked for deletion
        '404':
          description: Blob not found
  /{container}/{blob}?comp=metadata:
    get:
      operationId: getBlobMetadata
      summary: Azure Blob Storage Get blob metadata
      description: Retrieves all user-defined metadata of an existing blob or snapshot. Metadata is returned as x-ms-meta- response headers.
      tags:
      - Blobs
      parameters:
      - $ref: '#/components/parameters/ContainerName'
      - $ref: '#/components/parameters/BlobName'
      - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Blob metadata returned in response headers
    put:
      operationId: setBlobMetadata
      summary: Azure Blob Storage Set blob metadata
      description: Sets user-defined metadata for the specified blob as one or more name-value pairs. Existing metadata is replaced entirely.
      tags:
      - Blobs
      parameters:
      - $ref: '#/components/parameters/ContainerName'
      - $ref: '#/components/parameters/BlobName'
      - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Blob metadata set successfully
  /{container}/{blob}?comp=properties:
    put:
      operationId: setBlobHTTPHeaders
      summary: Azure Blob Storage Set blob HTTP headers
      description: Sets system properties defined for an existing blob such as content type, content encoding, content language, content disposition, and cache control.
      tags:
      - Blobs
      parameters:
      - $ref: '#/components/parameters/ContainerName'
      - $ref: '#/components/parameters/BlobName'
      - $ref: '#/components/parameters/ApiVersion'
      - name: x-ms-blob-content-type
        in: header
        description: The MIME content type of the blob.
        schema:
          type: string
      - name: x-ms-blob-content-encoding
        in: header
        description: The content encoding of the blob.
        schema:
          type: string
      - name: x-ms-blob-content-language
        in: header
        description: The content language of the blob.
        schema:
          type: string
      - name: x-ms-blob-cache-control
        in: header
        description: The cache control directive for the blob.
        schema:
          type: string
      - name: x-ms-blob-content-disposition
        in: header
        description: The content disposition of the blob.
        schema:
          type: string
      responses:
        '200':
          description: Blob HTTP headers set successfully
  /{container}/{blob}?comp=tags:
    get:
      operationId: getBlobTags
      summary: Azure Blob Storage Get blob tags
      description: Retrieves user-defined blob index tags. Tags form a secondary index that can be queried using the Find Blobs by Tags operation.
      tags:
      - Blobs
      parameters:
      - $ref: '#/components/parameters/ContainerName'
      - $ref: '#/components/parameters/BlobName'
      - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Blob tags returned
    put:
      operationId: setBlobTags
      summary: Azure Blob Storage Set blob tags
      description: Sets user-defined blob index tags on an existing blob. Tags are key-value pairs that form a secondary index, enabling efficient querying across all blobs in a storage account.
      tags:
      - Blobs
      parameters:
      - $ref: '#/components/parameters/ContainerName'
      - $ref: '#/components/parameters/BlobName'
      - $ref: '#/components/parameters/ApiVersion'
      responses:
        '204':
          description: Blob tags set successfully
  /{container}/{blob}?comp=lease:
    put:
      operationId: leaseBlob
      summary: Azure Blob Storage Lease blob
      description: Establishes and manages a lock on write and delete operations for a blob. The lock can be infinite or between 15 and 60 seconds.
      tags:
      - Blobs
      parameters:
      - $ref: '#/components/parameters/ContainerName'
      - $ref: '#/components/parameters/BlobName'
      - $ref: '#/components/parameters/ApiVersion'
      - name: x-ms-lease-action
        in: header
        required: true
        description: The lease action to perform.
        schema:
          type: string
          enum:
          - acquire
          - renew
          - change
          - release
          - break
      responses:
        '200':
          description: Lease operation completed
        '201':
          description: Lease acquired
  /{container}/{blob}?comp=snapshot:
    put:
      operationId: snapshotBlob
      summary: Azure Blob Storage Snapshot blob
      description: Creates a read-only snapshot of a blob. A snapshot is a version of a blob that is captured at a point in time. Snapshots share the same blob name and are distinguished by the snapshot query parameter.
      tags:
      - Blobs
      parameters:
      - $ref: '#/components/parameters/ContainerName'
      - $ref: '#/components/parameters/BlobName'
      - $ref: '#/components/parameters/ApiVersion'
      responses:
        '201':
          description: Snapshot created
  /{container}/{blob}?comp=copy:
    put:
      operationId: copyBlob
      summary: Azure Blob Storage Copy blob
      description: Copies a source blob to a destination blob within the same storage account or across storage accounts. The copy operation is asynchronous and the status can be checked using Get Blob Properties.
      tags:
      - Blobs
      parameters:
      - $ref: '#/components/parameters/ContainerName'
      - $ref: '#/components/parameters/BlobName'
      - $ref: '#/components/parameters/ApiVersion'
      - name: x-ms-copy-source
        in: header
        required: true
        description: URL of the source blob, up to 2 KiB in length.
        schema:
          type: string
          format: uri
      - name: x-ms-access-tier
        in: header
        description: The tier to set on the destination blob.
        schema:
          type: string
          enum:
          - Hot
          - Cool
          - Cold
          - Archive
      responses:
        '202':
          description: Copy operation initiated
  /{container}/{blob}?comp=copy&copyid={copyId}:
    put:
      operationId: abortCopyBlob
      summary: Azure Blob Storage Abort copy blob
      description: Aborts a pending Copy Blob operation and leaves the destination blob with zero length and full metadata. The copy must be in a pending state.
      tags:
      - Blobs
      parameters:
      - $ref: '#/components/parameters/ContainerName'
      - $ref: '#/components/parameters/BlobName'
      - $ref: '#/components/parameters/ApiVersion'
      - name: copyId
        in: query
        required: true
        description: The copy operation identifier returned by the Copy Blob response.
        schema:
          type: string
      - name: x-ms-copy-action
        in: header
        required: true
        schema:
          type: string
          enum:
          - abort
      responses:
        '204':
          description: Copy operation aborted
  /{container}/{blob}?comp=undelete:
    put:
      operationId: undeleteBlob
      summary: Azure Blob Storage Undelete blob
      description: Restores the contents and metadata of a soft-deleted blob and any associated soft-deleted snapshots. This is only available when soft delete is enabled and the retention period has not expired.
      tags:
      - Blobs
      parameters:
      - $ref: '#/components/parameters/ContainerName'
      - $ref: '#/components/parameters/BlobName'
      - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Blob undeleted successfully
  /{container}/{blob}?comp=tier:
    put:
      operationId: setBlobTier
      summary: Azure Blob Storage Set blob tier
      description: Sets the access tier of a block blob or page blob. For block blobs, supported tiers are Hot, Cool, Cold, and Archive. Moving a blob from Archive tier requires rehydration, which can take hours.
      tags:
      - Blobs
      parameters:
      - $ref: '#/components/parameters/ContainerName'
      - $ref: '#/components/parameters/BlobName'
      - $ref: '#/components/parameters/ApiVersion'
      - name: x-ms-access-tier
        in: header
        required: true
        description: The access tier to set for the blob.
        schema:
          type: string
          enum:
          - Hot
          - Cool
          - Cold
          - Archive
      - name: x-ms-rehydrate-priority
        in: header
        description: Priority of rehydration when moving a blob out of the Archive tier. Standard priority may take up to 15 hours, High priority within 1 hour at a higher cost.
        schema:
          type: string
          enum:
          - High
          - Standard
      responses:
        '200':
          description: Blob tier set successfully
        '202':
          description: Tier change accepted with rehydration pending
  /{container}/{blob}?comp=immutabilityPolicies:
    put:
      operationId: setBlobImmutabilityPolicy
      summary: Azure Blob Storage Set blob immutability policy
      description: Sets the immutability policy on a blob. Immutability policies prevent blob modification and deletion for a specified retention period. Supports unlocked and locked policy modes.
      tags:
      - Blobs
      parameters:
      - $ref: '#/components/parameters/ContainerName'
      - $ref: '#/components/parameters/BlobName'
      - $ref: '#/components/parameters/ApiVersion'
      - name: x-ms-immutability-policy-until-date
        in: header
        required: true
        description: The date until which the immutability policy is in effect.
        schema:
          type: string
          format: date-time
      - name: x-ms-immutability-policy-mode
        in: header
        required: true
        description: The mode of the immutability policy.
        schema:
          type: string
          enum:
          - Unlocked
          - Locked
          - Mutable
      responses:
        '200':
          description: Immutability policy set successfully
    delete:
      operationId: deleteBlobImmutabilityPolicy
      summary: Azure Blob Storage Delete blob immutability policy
      description: Deletes the immutability policy on a blob. The policy must be in Unlocked mode to be deleted.
      tags:
      - Blobs
      parameters:
      - $ref: '#/components/parameters/ContainerName'
      - $ref: '#/components/parameters/BlobName'
      - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: Immutability policy deleted
  /{container}/{blob}?comp=legalhold:
    put:
      operationId: setBlobLegalHold
      summary: Azure Blob Storage Set blob legal hold
      description: Sets or clears a legal hold on a blob. A legal hold prevents the blob from being modified or deleted regardless of the immutability policy.
      tags:
      - Blobs
      parameters:
      - $ref: '#/components/parameters/ContainerName'
      - $ref: '#/components/parameters/BlobName'
      - $ref: '#/components/parameters/ApiVersion'
      - name: x-ms-legal-hold
        in: header
        required: true
        description: Whether to set or clear the legal hold.
        schema:
          type: boolean
      responses:
        '200':
          description: Legal hold set or cleared
components:
  parameters:
    ContainerName:
      name: container
      in: path
      required: true
      description: The container name. Must be a valid DNS name, 3 to 63 characters, starting with a letter or number, and containing only lowercase letters, numbers, and hyphens.
      schema:
        type: string
        pattern: ^[a-z0-9](?!.*--)[a-z0-9-]{1,61}[a-z0-9]$
    BlobName:
      name: blob
      in: path
      required: true
      description: The blob name. Can contain any combination of characters and may include path separators (/) for organizing blobs in a virtual directory hierarchy.
      schema:
        type: string
    ApiVersion:
      name: x-ms-version
      in: header
      required: true
      description: Specifies the version of the Azure Storage REST API to use for the request.
      schema:
        type: string
        default: '2024-11-04'
  securitySchemes:
    sharedKey:
      type: apiKey
      in: header
      name: Authorization
      description: Azure Storage shared key authorization using the storage account access key.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Microsoft Entra ID OAuth 2.0 bearer token for accessing blob resources.
    sharedAccessSignature:
      type: apiKey
      in: query
      name: sig
      description: Shared access signature (SAS) token granting delegated access to blob resources.
externalDocs:
  description: Azure Blob Storage REST API Documentation
  url: https://learn.microsoft.com/en-us/rest/api/storageservices/blob-service-rest-api