Azure Queue Storage Message API

openapi: 3.2.0
info:
  title: Azure Queue Storage Message API
  version: '2026-04-06'
  x-ms-code-generation-settings:
    header: MIT
    strictSpecAdherence: false
  description: Azure Queue Storage data-plane REST API (version 2026-04-06), converted from Swagger 2.0 to OpenAPI 3.0.
  x-source: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/storage/data-plane/QueueStorage/stable/2026-04-06/queue.json
  x-ownership: Published by Microsoft in its official Azure/azure-rest-api-specs repository; info.title Azure Queue Storage; host template {accountName}.queue.core.windows.net is the documented Queue service endpoint.
servers:
- url: https://{accountName}.queue.core.windows.net
  variables:
    accountName:
      default: myaccount
      description: Storage account name
tags:
- name: Message
paths:
  /{queueName}/messages:
    parameters:
    - $ref: '#/components/parameters/QueueName'
    get:
      tags:
      - Message
      operationId: Messages_Dequeue
      description: The Dequeue operation retrieves one or more messages from the front of the queue.
      parameters:
      - $ref: '#/components/parameters/NumOfMessages'
      - $ref: '#/components/parameters/VisibilityTimeout'
      - $ref: '#/components/parameters/Timeout'
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/ClientRequestId'
      responses:
        '200':
          description: OK
          headers:
            x-ms-request-id:
              x-ms-client-name: RequestId
              description: This header uniquely identifies the request that was made and can be used for troubleshooting the request.
              schema:
                type: string
            x-ms-version:
              x-ms-client-name: Version
              description: Indicates the version of the Queue 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/DequeuedMessagesList'
        default:
          description: Failure
          headers:
            x-ms-error-code:
              x-ms-client-name: ErrorCode
              schema:
                type: string
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/StorageError'
      summary: Messages dequeue
      x-summary-source: derived
    delete:
      tags:
      - Message
      operationId: Messages_Clear
      description: The Clear operation deletes all messages from the specified queue.
      parameters:
      - $ref: '#/components/parameters/Timeout'
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/ClientRequestId'
      responses:
        '204':
          description: No Content
          headers:
            x-ms-request-id:
              x-ms-client-name: RequestId
              description: This header uniquely identifies the request that was made and can be used for troubleshooting the request.
              schema:
                type: string
            x-ms-version:
              x-ms-client-name: Version
              description: Indicates the version of the Queue 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
        default:
          description: Failure
          headers:
            x-ms-error-code:
              x-ms-client-name: ErrorCode
              schema:
                type: string
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/StorageError'
      summary: Messages clear
      x-summary-source: derived
    post:
      tags:
      - Message
      operationId: Messages_Enqueue
      description: The Enqueue operation adds a new message to the back of the message queue. A visibility timeout can also be specified to make the message invisible until the visibility timeout expires. A message must be in a format that can be included in an XML request with UTF-8 encoding. The encoded message can be up to 64 KB in size for versions 2011-08-18 and newer, or 8 KB in size for previous versions.
      parameters:
      - $ref: '#/components/parameters/VisibilityTimeoutForEnqueue'
      - $ref: '#/components/parameters/MessageTTL'
      - $ref: '#/components/parameters/Timeout'
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/ClientRequestId'
      requestBody:
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/QueueMessage'
        description: A Message object which can be stored in a Queue
        required: true
        x-ms-parameter-location: method
      responses:
        '201':
          description: Created
          headers:
            x-ms-request-id:
              x-ms-client-name: RequestId
              description: This header uniquely identifies the request that was made and can be used for troubleshooting the request.
              schema:
                type: string
            x-ms-version:
              x-ms-client-name: Version
              description: Indicates the version of the Queue 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/EnqueuedMessageList'
        default:
          description: Failure
          headers:
            x-ms-error-code:
              x-ms-client-name: ErrorCode
              schema:
                type: string
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/StorageError'
      summary: Messages enqueue
      x-summary-source: derived
  /{queueName}/messages?peekonly=true:
    parameters:
    - $ref: '#/components/parameters/QueueName'
    - name: peekonly
      description: Peek message(s).
      in: query
      required: true
      schema:
        type: string
        enum:
        - 'true'
    get:
      tags:
      - Message
      operationId: Messages_Peek
      description: The Peek operation retrieves one or more messages from the front of the queue, but does not alter the visibility of the message.
      parameters:
      - $ref: '#/components/parameters/NumOfMessages'
      - $ref: '#/components/parameters/Timeout'
      - $ref: '#/components/parameters/ApiVersionParameter'
      - $ref: '#/components/parameters/ClientRequestId'
      responses:
        '200':
          description: OK
          headers:
            x-ms-request-id:
              x-ms-client-name: RequestId
              description: This header uniquely identifies the request that was made and can be used for troubleshooting the request.
              schema:
                type: string
            x-ms-version:
              x-ms-client-name: Version
              description: Indicates the version of the Queue 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/PeekedMessagesList'
        default:
          description: Failure
          headers:
            x-ms-error-code:
              x-ms-client-name: ErrorCode
              schema:
                type: string
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/StorageError'
      summary: Messages peek
      x-summary-source: derived
components:
  schemas:
    DequeuedMessageItem:
      description: The object returned in the QueueMessageList array when calling Get Messages on a Queue.
      type: object
      required:
      - MessageId
      - InsertionTime
      - ExpirationTime
      - PopReceipt
      - TimeNextVisible
      - DequeueCount
      - MessageText
      properties:
        MessageId:
          type: string
          description: The Id of the Message.
        InsertionTime:
          type: string
          format: date-time-rfc1123
          description: The time the Message was inserted into the Queue.
        ExpirationTime:
          type: string
          format: date-time-rfc1123
          description: The time that the Message will expire and be automatically deleted.
        PopReceipt:
          type: string
          description: This value is required to delete the Message. If deletion fails using this popreceipt then the message has been dequeued by another client.
        TimeNextVisible:
          type: string
          format: date-time-rfc1123
          description: The time that the message will again become visible in the Queue.
        DequeueCount:
          type: integer
          format: int64
          description: The number of times the message has been dequeued.
        MessageText:
          type: string
          description: The content of the Message.
      xml:
        wrapped: true
        name: QueueMessage
    EnqueuedMessage:
      description: The object returned in the QueueMessageList array when calling Put Message on a Queue
      type: object
      required:
      - MessageId
      - InsertionTime
      - ExpirationTime
      - PopReceipt
      - TimeNextVisible
      properties:
        MessageId:
          type: string
          description: The Id of the Message.
        InsertionTime:
          type: string
          format: date-time-rfc1123
          description: The time the Message was inserted into the Queue.
        ExpirationTime:
          type: string
          format: date-time-rfc1123
          description: The time that the Message will expire and be automatically deleted.
        PopReceipt:
          type: string
          description: This value is required to delete the Message. If deletion fails using this popreceipt then the message has been dequeued by another client.
        TimeNextVisible:
          type: string
          format: date-time-rfc1123
          description: The time that the message will again become visible in the Queue.
      xml:
        wrapped: true
        name: QueueMessage
    QueueMessage:
      description: A Message object which can be stored in a Queue
      type: object
      required:
      - MessageText
      properties:
        MessageText:
          type: string
          description: The content of the message
    EnqueuedMessageList:
      description: The object returned when calling Put Message on a Queue
      type: array
      items:
        $ref: '#/components/schemas/EnqueuedMessage'
      xml:
        wrapped: true
        name: QueueMessagesList
    PeekedMessagesList:
      description: The object returned when calling Peek Messages on a Queue
      type: array
      items:
        $ref: '#/components/schemas/PeekedMessageItem'
      xml:
        wrapped: true
        name: QueueMessagesList
    PeekedMessageItem:
      description: The object returned in the QueueMessageList array when calling Peek Messages on a Queue
      type: object
      required:
      - MessageId
      - InsertionTime
      - ExpirationTime
      - DequeueCount
      - MessageText
      properties:
        MessageId:
          type: string
          description: The Id of the Message.
        InsertionTime:
          type: string
          format: date-time-rfc1123
          description: The time the Message was inserted into the Queue.
        ExpirationTime:
          type: string
          format: date-time-rfc1123
          description: The time that the Message will expire and be automatically deleted.
        DequeueCount:
          type: integer
          format: int64
          description: The number of times the message has been dequeued.
        MessageText:
          type: string
          description: The content of the Message.
      xml:
        wrapped: true
        name: QueueMessage
    StorageError:
      type: object
      properties:
        Message:
          type: string
    DequeuedMessagesList:
      description: The object returned when calling Get Messages on a Queue
      type: array
      items:
        $ref: '#/components/schemas/DequeuedMessageItem'
      xml:
        wrapped: true
        name: QueueMessagesList
  parameters:
    VisibilityTimeout:
      name: visibilitytimeout
      in: query
      required: false
      x-ms-parameter-location: method
      description: Optional. Specifies the new visibility timeout value, in seconds, relative to server time. The default value is 30 seconds. A specified value must be larger than or equal to 1 second, and cannot be larger than 7 days, or larger than 2 hours on REST protocol versions prior to version 2011-08-18. The visibility timeout of a message can be set to a value later than the expiry time.
      schema:
        type: integer
        minimum: 0
        maximum: 604800
    QueueName:
      name: queueName
      in: path
      required: true
      x-ms-parameter-location: method
      description: The queue name.
      schema:
        type: string
    ApiVersionParameter:
      name: x-ms-version
      x-ms-parameter-location: client
      x-ms-client-name: version
      in: header
      required: true
      description: Specifies the version of the operation to use for this request.
      schema:
        type: string
    VisibilityTimeoutForEnqueue:
      name: visibilitytimeout
      in: query
      required: false
      x-ms-parameter-location: method
      description: Optional. If specified, the request must be made using an x-ms-version of 2011-08-18 or later. If not specified, the default value is 0. Specifies the new visibility timeout value, in seconds, relative to server time. The new value must be larger than or equal to 0, and cannot be larger than 7 days. The visibility timeout of a message cannot be set to a value later than the expiry time. visibilitytimeout should be set to a value smaller than the time-to-live value.
      schema:
        type: integer
        minimum: 0
        maximum: 604800
    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
    NumOfMessages:
      name: numofmessages
      x-ms-client-name: numberOfMessages
      in: query
      required: false
      x-ms-parameter-location: method
      description: Optional. A nonzero integer value that specifies the number of messages to retrieve from the queue, up to a maximum of 32. If fewer are visible, the visible messages are returned. By default, a single message is retrieved from the queue with this operation.
      schema:
        type: integer
        minimum: 1
    MessageTTL:
      name: messagettl
      x-ms-client-name: MessageTimeToLive
      in: query
      required: false
      x-ms-parameter-location: method
      description: Optional. Specifies the time-to-live interval for the message, in seconds. Prior to version 2017-07-29, the maximum time-to-live allowed is 7 days. For version 2017-07-29 or later, the maximum time-to-live can be any positive number, as well as -1 indicating that the message does not expire. If this parameter is omitted, the default time-to-live is 7 days.
      schema:
        type: integer
        minimum: -1
    Timeout:
      name: timeout
      in: query
      required: false
      x-ms-parameter-location: method
      description: The The timeout parameter is expressed in seconds. For more information, see <a href="https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-queue-service-operations>Setting Timeouts for Queue Service Operations.</a>
      schema:
        type: integer
        minimum: 0
  securitySchemes:
    queue_shared_key:
      type: apiKey
      name: Authorization
      in: header