openapi: 3.0.3
info:
  title: Cloudflare Queues Consumer Messages API
  description: REST API for creating and managing Cloudflare Queues, sending and receiving messages, configuring consumers (Worker push or HTTP pull), managing dead letter queues, purging queues, and retrieving queue metrics and event subscriptions. Authenticated with Cloudflare API tokens via Bearer authorization.
  version: 1.0.0
  contact:
    name: Cloudflare Developer Docs
    url: https://developers.cloudflare.com/queues/
  license:
    name: Cloudflare Terms of Service
    url: https://www.cloudflare.com/terms/
servers:
- url: https://api.cloudflare.com/client/v4
  description: Cloudflare API v4
security:
- api_token: []
tags:
- name: Messages
  description: Operations for sending, receiving, and acknowledging messages
paths:
  /accounts/{account_id}/queues/{queue_id}/messages:
    post:
      description: Push a message to a Queue
      operationId: queues-push-message
      summary: Push Message
      tags:
      - Messages
      parameters:
      - in: path
        name: queue_id
        required: true
        schema:
          $ref: '#/components/schemas/mq_identifier'
      - in: path
        name: account_id
        required: true
        schema:
          $ref: '#/components/schemas/mq_identifier'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/mq_queue-message'
      responses:
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mq_api-v4-failure'
          description: Failure response
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/mq_api-v4-success'
                - properties:
                    result:
                      properties:
                        metadata:
                          properties:
                            metrics:
                              $ref: '#/components/schemas/mq_queue-metrics'
                          type: object
                      type: object
                  type: object
                type: object
          description: Successful message ingestion.
  /accounts/{account_id}/queues/{queue_id}/messages/ack:
    post:
      description: Acknowledge + Retry messages from a Queue
      operationId: queues-ack-messages
      summary: Acknowledge + Retry Queue Messages
      tags:
      - Messages
      parameters:
      - in: path
        name: queue_id
        required: true
        schema:
          $ref: '#/components/schemas/mq_identifier'
      - in: path
        name: account_id
        required: true
        schema:
          $ref: '#/components/schemas/mq_identifier'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                acks:
                  items:
                    properties:
                      lease_id:
                        $ref: '#/components/schemas/mq_lease-id'
                    type: object
                  type: array
                retries:
                  items:
                    properties:
                      delay_seconds:
                        $ref: '#/components/schemas/mq_retry-delay'
                      lease_id:
                        $ref: '#/components/schemas/mq_lease-id'
                    type: object
                  type: array
              type: object
      responses:
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mq_api-v4-failure'
          description: Failure response
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/mq_api-v4-success'
                - properties:
                    result:
                      properties:
                        ackCount:
                          description: The number of messages that were successfully acknowledged.
                          example: 5
                          type: number
                        retryCount:
                          description: The number of messages that were successfully retried.
                          example: 5
                          type: number
                        warnings:
                          additionalProperties:
                            type: string
                          description: Map of lease IDs to warning messages encountered during acknowledgement.
                          type: object
                      type: object
                  type: object
                type: object
          description: Details of ACKs and retries
  /accounts/{account_id}/queues/{queue_id}/messages/batch:
    post:
      description: Push a batch of messages to a Queue
      operationId: queues-push-messages
      summary: Push Message Batch
      tags:
      - Messages
      parameters:
      - in: path
        name: queue_id
        required: true
        schema:
          $ref: '#/components/schemas/mq_identifier'
      - in: path
        name: account_id
        required: true
        schema:
          $ref: '#/components/schemas/mq_identifier'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/mq_queue-batch'
      responses:
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mq_api-v4-failure'
          description: Failure response
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/mq_api-v4-success'
                - properties:
                    result:
                      properties:
                        metadata:
                          properties:
                            metrics:
                              $ref: '#/components/schemas/mq_queue-metrics'
                          type: object
                      type: object
                  type: object
                type: object
          description: Successful batch ingestion.
  /accounts/{account_id}/queues/{queue_id}/messages/preview:
    post:
      description: Preview messages from a Queue without leasing them. Messages remain available for subsequent preview or pull operations.
      operationId: queues-preview-messages
      summary: Preview Queue Messages
      tags:
      - Messages
      parameters:
      - in: path
        name: queue_id
        required: true
        schema:
          $ref: '#/components/schemas/mq_identifier'
      - in: path
        name: account_id
        required: true
        schema:
          $ref: '#/components/schemas/mq_identifier'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                batch_size:
                  $ref: '#/components/schemas/mq_batch-size'
              type: object
      responses:
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mq_api-v4-failure'
          description: Failure response
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/mq_api-v4-success'
                - properties:
                    result:
                      properties:
                        messages:
                          $ref: '#/components/schemas/mq_queue-pull-batch'
                      type: object
                  type: object
                type: object
          description: A batch of previewed messages from the Queue
  /accounts/{account_id}/queues/{queue_id}/messages/preview/ack:
    post:
      description: Delete previewed messages from a Queue. Note that messages acknowledged this way are not considered delivered; they are instantly deleted from this queue and do not affect metrics.
      operationId: queues-ack-preview-messages
      summary: Delete Previewed Queue Messages
      tags:
      - Messages
      parameters:
      - in: path
        name: queue_id
        required: true
        schema:
          $ref: '#/components/schemas/mq_identifier'
      - in: path
        name: account_id
        required: true
        schema:
          $ref: '#/components/schemas/mq_identifier'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                acks:
                  items:
                    properties:
                      lease_id:
                        $ref: '#/components/schemas/mq_lease-id'
                    type: object
                  type: array
                retries:
                  items:
                    properties:
                      delay_seconds:
                        $ref: '#/components/schemas/mq_retry-delay'
                      lease_id:
                        $ref: '#/components/schemas/mq_lease-id'
                    type: object
                  type: array
              type: object
        required: true
      responses:
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mq_api-v4-failure'
          description: Failure response
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/mq_api-v4-success'
                - properties:
                    result:
                      properties:
                        warnings:
                          additionalProperties:
                            type: string
                          description: Map of lease IDs to warning messages encountered during acknowledgement.
                          type: object
                      type: object
                  type: object
                type: object
          description: Result of acknowledging previewed messages
  /accounts/{account_id}/queues/{queue_id}/messages/pull:
    post:
      description: Pull a batch of messages from a Queue
      operationId: queues-pull-messages
      summary: Pull Queue Messages
      tags:
      - Messages
      parameters:
      - in: path
        name: queue_id
        required: true
        schema:
          $ref: '#/components/schemas/mq_identifier'
      - in: path
        name: account_id
        required: true
        schema:
          $ref: '#/components/schemas/mq_identifier'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                batch_size:
                  $ref: '#/components/schemas/mq_batch-size'
                visibility_timeout_ms:
                  $ref: '#/components/schemas/mq_visibility-timeout'
              type: object
      responses:
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mq_api-v4-failure'
          description: Failure response
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/mq_api-v4-success'
                - properties:
                    result:
                      properties:
                        message_backlog_count:
                          description: The number of unacknowledged messages in the queue.
                          example: 5
                          type: number
                        messages:
                          $ref: '#/components/schemas/mq_queue-pull-batch'
                        metadata:
                          properties:
                            metrics:
                              $ref: '#/components/schemas/mq_queue-metrics'
                          type: object
                      type: object
                  type: object
                type: object
          description: A batch of messages in the Queue
components:
  schemas:
    mq_api-v4-success:
      properties:
        errors:
          $ref: '#/components/schemas/mq_api-v4-error'
        messages:
          $ref: '#/components/schemas/mq_api-v4-message'
        success:
          description: Indicates if the API call was successful or not.
          enum:
          - true
          type: boolean
      type: object
    mq_visibility-timeout:
      description: The number of milliseconds that a message is exclusively leased. After the timeout, the message becomes available for another attempt.
      example: 6000
      type: number
    mq_queue-batch:
      properties:
        delay_seconds:
          description: The number of seconds to wait for attempting to deliver this batch to consumers
          example: 0
          type: number
        messages:
          items:
            $ref: '#/components/schemas/mq_queue-message'
          type: array
      type: object
    mq_retry-delay:
      description: The number of seconds to delay before making the message available for another attempt.
      example: 10
      type: number
    mq_queue-message-json:
      properties:
        body:
          type: object
        content_type:
          enum:
          - json
          type: string
      type: object
    mq_api-v4-failure:
      properties:
        errors:
          $ref: '#/components/schemas/mq_api-v4-error'
        messages:
          $ref: '#/components/schemas/mq_api-v4-message'
        success:
          description: Indicates if the API call was successful or not.
          enum:
          - false
          example: false
          type: boolean
      type: object
    mq_queue-message:
      allOf:
      - properties:
          delay_seconds:
            description: The number of seconds to wait for attempting to deliver this message to consumers
            example: 0
            type: number
        type: object
      - oneOf:
        - $ref: '#/components/schemas/mq_queue-message-text'
        - $ref: '#/components/schemas/mq_queue-message-json'
    mq_api-v4-message:
      example: []
      items:
        type: string
      type: array
    mq_identifier:
      description: A Resource identifier.
      example: 023e105f4ecef8ad9ca31a8372d0c353
      maxLength: 32
      readOnly: true
      type: string
    mq_queue-message-text:
      properties:
        body:
          type: string
        content_type:
          enum:
          - text
          type: string
      type: object
    mq_api-v4-error:
      example:
      - code: 7003
        message: No route for the URI
      items:
        properties:
          code:
            minimum: 1000
            type: integer
          message:
            type: string
        required:
        - code
        - message
        type: object
        uniqueItems: true
      minLength: 1
      type: array
    mq_queue-metrics:
      description: Best-effort metrics for the queue. Values may be approximate due to the distributed nature of queues.
      properties:
        backlog_bytes:
          description: The size in bytes of unacknowledged messages in the queue.
          example: 1024
          type: number
        backlog_count:
          description: The number of unacknowledged messages in the queue.
          example: 5
          type: number
        oldest_message_timestamp_ms:
          description: Unix timestamp in milliseconds of the oldest unacknowledged message in the queue. Returns 0 if unknown.
          example: 1710950954154
          type: number
      required:
      - backlog_count
      - backlog_bytes
      - oldest_message_timestamp_ms
      type: object
    mq_lease-id:
      description: An ID that represents an "in-flight" message that has been pulled from a Queue. You must hold on to this ID and use it to acknowledge this message.
      example: eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIn0..Q8p21d7dceR6vUfwftONdQ.JVqZgAS-Zk7MqmqccYtTHeeMElNHaOMigeWdb8LyMOg.T2_HV99CYzGaQuhTyW8RsgbnpTRZHRM6N7UoSaAKeK0
      type: string
    mq_batch-size:
      description: The maximum number of messages to include in a batch.
      example: 50
      type: number
    mq_queue-pull-batch:
      items:
        properties:
          attempts:
            example: 1
            readOnly: true
            type: number
          body:
            example: hello world
            readOnly: true
            type: string
          id:
            example: b01b5594f784d0165c2985833f5660dd
            readOnly: true
            type: string
          lease_id:
            $ref: '#/components/schemas/mq_lease-id'
          metadata:
            example:
              CF-Content-Type: text
              CF-sourceMessageSource: dash
            readOnly: true
            type: object
          timestamp_ms:
            example: 1710950954154
            readOnly: true
            type: number
        type: object
      type: array
  securitySchemes:
    api_token:
      type: http
      scheme: bearer
      description: Cloudflare API Token (Bearer)
    api_email:
      type: apiKey
      in: header
      name: X-Auth-Email
      description: Cloudflare account email address
    api_key:
      type: apiKey
      in: header
      name: X-Auth-Key
      description: Cloudflare Global API Key
externalDocs:
  description: Cloudflare Queues Documentation
  url: https://developers.cloudflare.com/queues/