The Cloudflare Queues API enables developers to create and manage message queues that integrate with Cloudflare Workers. Queues support guaranteed delivery, work offloading from requests, worker-to-worker communication, and data buffering and batching.
openapi: 3.1.0
info:
title: Cloudflare Queues API
description: >-
The Cloudflare Queues API enables developers to create and manage message
queues that integrate with Cloudflare Workers. Queues support guaranteed
delivery, work offloading from requests, worker-to-worker communication,
and data buffering and batching. The API provides endpoints for queue
management, consumer configuration, message operations, and purging.
version: '4.0'
contact:
name: Cloudflare Support
url: https://support.cloudflare.com/
termsOfService: https://www.cloudflare.com/terms/
externalDocs:
description: Cloudflare Queues API Documentation
url: https://developers.cloudflare.com/api/resources/queues/
servers:
- url: https://api.cloudflare.com/client/v4
description: Cloudflare API v4 Production Server
tags:
- name: Consumers
description: >-
Manage consumers that process messages from queues.
- name: Messages
description: >-
Send, pull, and acknowledge messages.
- name: Purge
description: >-
Purge all messages from a queue.
- name: Queues
description: >-
Create, list, update, and delete message queues.
security:
- bearerAuth: []
paths:
/accounts/{account_id}/queues:
get:
operationId: listQueues
summary: Cloudflare List Queues
description: >-
Returns all queues owned by the account.
tags:
- Queues
parameters:
- $ref: '#/components/parameters/AccountId'
responses:
'200':
description: List of queues.
content:
application/json:
schema:
$ref: '#/components/schemas/QueueListResponse'
examples:
Listqueues200Example:
summary: Default listQueues 200 response
x-microcks-default: true
value:
result:
- queue_id: '500123'
queue_name: example_value
created_on: '2026-01-15T10:30:00Z'
modified_on: '2026-01-15T10:30:00Z'
producers_total_count: 10
consumers_total_count: 10
success: true
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createQueue
summary: Cloudflare Create Queue
description: >-
Create a new message queue for the account.
tags:
- Queues
parameters:
- $ref: '#/components/parameters/AccountId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- queue_name
properties:
queue_name:
type: string
description: The name of the queue.
examples:
CreatequeueRequestExample:
summary: Default createQueue request
x-microcks-default: true
value:
queue_name: example_value
responses:
'200':
description: Queue created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/QueueResponse'
examples:
Createqueue200Example:
summary: Default createQueue 200 response
x-microcks-default: true
value:
result:
queue_id: '500123'
queue_name: example_value
created_on: '2026-01-15T10:30:00Z'
modified_on: '2026-01-15T10:30:00Z'
producers_total_count: 10
consumers_total_count: 10
success: true
errors:
- {}
messages:
- {}
'400':
description: Bad request.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/accounts/{account_id}/queues/{queue_id}:
get:
operationId: getQueue
summary: Cloudflare Get Queue
description: >-
Retrieve details of a specific queue.
tags:
- Queues
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/QueueId'
responses:
'200':
description: Queue details.
content:
application/json:
schema:
$ref: '#/components/schemas/QueueResponse'
examples:
Getqueue200Example:
summary: Default getQueue 200 response
x-microcks-default: true
value:
result:
queue_id: '500123'
queue_name: example_value
created_on: '2026-01-15T10:30:00Z'
modified_on: '2026-01-15T10:30:00Z'
producers_total_count: 10
consumers_total_count: 10
success: true
errors:
- {}
messages:
- {}
'401':
description: Unauthorized.
'404':
description: Queue not found.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: replaceQueue
summary: Cloudflare Replace Queue Configuration
description: >-
Overwrite the queue configuration.
tags:
- Queues
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/QueueId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
queue_name:
type: string
description: The new name of the queue.
examples:
ReplacequeueRequestExample:
summary: Default replaceQueue request
x-microcks-default: true
value:
queue_name: example_value
responses:
'200':
description: Queue replaced successfully.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
operationId: updateQueue
summary: Cloudflare Update Queue Settings
description: >-
Partially update queue settings.
tags:
- Queues
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/QueueId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
queue_name:
type: string
description: The new name of the queue.
examples:
UpdatequeueRequestExample:
summary: Default updateQueue request
x-microcks-default: true
value:
queue_name: example_value
responses:
'200':
description: Queue updated successfully.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteQueue
summary: Cloudflare Delete Queue
description: >-
Remove a queue and all its messages.
tags:
- Queues
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/QueueId'
responses:
'200':
description: Queue deleted successfully.
'401':
description: Unauthorized.
'404':
description: Queue not found.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/accounts/{account_id}/queues/{queue_id}/consumers:
get:
operationId: listQueueConsumers
summary: Cloudflare List Queue Consumers
description: >-
Returns the consumers configured for a queue.
tags:
- Consumers
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/QueueId'
responses:
'200':
description: List of consumers.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createQueueConsumer
summary: Cloudflare Create Queue Consumer
description: >-
Add a new consumer to a queue to process messages.
tags:
- Consumers
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/QueueId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConsumerInput'
examples:
CreatequeueconsumerRequestExample:
summary: Default createQueueConsumer request
x-microcks-default: true
value:
script_name: example_value
settings:
batch_size: 10
max_retries: 10
max_wait_time_ms: 10
responses:
'200':
description: Consumer created successfully.
'400':
description: Bad request.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/accounts/{account_id}/queues/{queue_id}/consumers/{consumer_id}:
get:
operationId: getQueueConsumer
summary: Cloudflare Get Queue Consumer
description: >-
Retrieve details of a specific queue consumer.
tags:
- Consumers
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/QueueId'
- $ref: '#/components/parameters/ConsumerId'
responses:
'200':
description: Consumer details.
'401':
description: Unauthorized.
'404':
description: Consumer not found.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: replaceQueueConsumer
summary: Cloudflare Replace Queue Consumer
description: >-
Update or create a consumer for the queue.
tags:
- Consumers
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/QueueId'
- $ref: '#/components/parameters/ConsumerId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConsumerInput'
examples:
ReplacequeueconsumerRequestExample:
summary: Default replaceQueueConsumer request
x-microcks-default: true
value:
script_name: example_value
settings:
batch_size: 10
max_retries: 10
max_wait_time_ms: 10
responses:
'200':
description: Consumer replaced successfully.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteQueueConsumer
summary: Cloudflare Delete Queue Consumer
description: >-
Remove a consumer from the queue.
tags:
- Consumers
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/QueueId'
- $ref: '#/components/parameters/ConsumerId'
responses:
'200':
description: Consumer deleted successfully.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/accounts/{account_id}/queues/{queue_id}/messages:
post:
operationId: sendMessage
summary: Cloudflare Send Message
description: >-
Send a single message to the queue.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/QueueId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MessageInput'
examples:
SendmessageRequestExample:
summary: Default sendMessage request
x-microcks-default: true
value:
body: example_value
content_type: json
responses:
'200':
description: Message sent successfully.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/accounts/{account_id}/queues/{queue_id}/messages/batch:
post:
operationId: sendMessageBatch
summary: Cloudflare Send Message Batch
description: >-
Send multiple messages to the queue in a single request.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/QueueId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
messages:
type: array
items:
$ref: '#/components/schemas/MessageInput'
examples:
SendmessagebatchRequestExample:
summary: Default sendMessageBatch request
x-microcks-default: true
value:
messages:
- body: example_value
content_type: json
responses:
'200':
description: Messages sent successfully.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/accounts/{account_id}/queues/{queue_id}/messages/pull:
post:
operationId: pullMessages
summary: Cloudflare Pull Messages
description: >-
Retrieve a batch of messages from the queue for processing.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/QueueId'
requestBody:
content:
application/json:
schema:
type: object
properties:
visibility_timeout_ms:
type: integer
description: >-
How long the pulled messages should be invisible to other
consumers, in milliseconds.
batch_size:
type: integer
description: Maximum number of messages to pull.
examples:
PullmessagesRequestExample:
summary: Default pullMessages request
x-microcks-default: true
value:
visibility_timeout_ms: 10
batch_size: 10
responses:
'200':
description: Messages pulled successfully.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/accounts/{account_id}/queues/{queue_id}/messages/ack:
post:
operationId: ackMessages
summary: Cloudflare Acknowledge Messages
description: >-
Acknowledge and optionally retry messages from the queue. Acknowledged
messages are permanently removed from the queue.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/QueueId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
acks:
type: array
items:
type: object
properties:
lease_id:
type: string
description: The lease ID from the pulled message.
retries:
type: array
items:
type: object
properties:
lease_id:
type: string
description: The lease ID of the message to retry.
delay_seconds:
type: integer
description: Delay before the message becomes visible again.
examples:
AckmessagesRequestExample:
summary: Default ackMessages request
x-microcks-default: true
value:
acks:
- lease_id: '500123'
retries:
- lease_id: '500123'
delay_seconds: 10
responses:
'200':
description: Messages acknowledged successfully.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/accounts/{account_id}/queues/{queue_id}/purge:
get:
operationId: getPurgeStatus
summary: Cloudflare Get Purge Status
description: >-
Check the status of a queue purge operation.
tags:
- Purge
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/QueueId'
responses:
'200':
description: Purge status.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: purgeQueue
summary: Cloudflare Purge Queue
description: >-
Delete all messages from the queue.
tags:
- Purge
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/QueueId'
responses:
'200':
description: Purge initiated successfully.
'401':
description: Unauthorized.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
API token with Queues permissions.
parameters:
AccountId:
name: account_id
in: path
required: true
description: The unique identifier of the Cloudflare account.
schema:
type: string
QueueId:
name: queue_id
in: path
required: true
description: The unique identifier of the queue.
schema:
type: string
ConsumerId:
name: consumer_id
in: path
required: true
description: The unique identifier of the consumer.
schema:
type: string
schemas:
Queue:
type: object
properties:
queue_id:
type: string
description: The unique identifier of the queue.
example: '500123'
queue_name:
type: string
description: The name of the queue.
example: example_value
created_on:
type: string
format: date-time
description: When the queue was created.
example: '2026-01-15T10:30:00Z'
modified_on:
type: string
format: date-time
description: When the queue was last modified.
example: '2026-01-15T10:30:00Z'
producers_total_count:
type: integer
description: Number of producers attached.
example: 10
consumers_total_count:
type: integer
description: Number of consumers attached.
example: 10
QueueResponse:
type: object
properties:
result:
$ref: '#/components/schemas/Queue'
success:
type: boolean
example: true
errors:
type: array
items:
type: object
example: []
messages:
type: array
items:
type: object
example: []
QueueListResponse:
type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/Queue'
example: []
success:
type: boolean
example: true
ConsumerInput:
type: object
properties:
script_name:
type: string
description: The Worker script name that will consume messages.
example: example_value
settings:
type: object
properties:
batch_size:
type: integer
description: Maximum number of messages per batch.
max_retries:
type: integer
description: Maximum number of retries for failed messages.
max_wait_time_ms:
type: integer
description: Maximum time to wait for a full batch in milliseconds.
example: example_value
MessageInput:
type: object
properties:
body:
description: The message body content.
example: example_value
content_type:
type: string
description: The content type of the message body.
enum:
- json
- text
- bytes
example: json