OpenAPI Specification
openapi: 3.0.3
info:
title: QStash Dead Letter Queue Queues API
description: QStash is a serverless message queue and task scheduling REST API from Upstash that delivers HTTP messages to endpoints reliably without requiring any long-lived connections or infrastructure management. Built entirely on stateless HTTP requests, it is designed for serverless and edge runtimes where traditional message brokers are impractical. QStash supports automatic retries, CRON-based scheduling up to one year in advance, URL group broadcasting for fan-out delivery, FIFO queuing, dead-letter queues, and message deduplication.
version: '2.0'
contact:
name: Upstash Support
url: https://upstash.com/docs/qstash/overall/getstarted
license:
name: Upstash Terms of Service
url: https://upstash.com/trust/terms.pdf
servers:
- url: https://qstash.upstash.io/v2
description: QStash production API
security:
- BearerAuth: []
tags:
- name: Queues
description: Manage FIFO queues
paths:
/enqueue/{queueName}/{destination}:
post:
operationId: enqueueMessage
summary: Enqueue a message to a FIFO queue
description: Add a message to the specified FIFO queue for ordered delivery to the destination URL.
tags:
- Queues
parameters:
- name: queueName
in: path
required: true
description: Name of the target queue
schema:
type: string
- name: destination
in: path
required: true
description: Destination URL for message delivery
schema:
type: string
- name: Upstash-Delay
in: header
description: Delay message delivery by this duration
schema:
type: string
- name: Upstash-Retries
in: header
description: Number of retry attempts
schema:
type: integer
- name: Upstash-Deduplication-Id
in: header
description: Manual deduplication ID
schema:
type: string
requestBody:
description: Message payload
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'201':
description: Message enqueued successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PublishResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
/queues/:
post:
operationId: upsertQueue
summary: Create or update a queue
description: Create a new queue or update an existing queue's configuration such as parallelism. Queues provide FIFO ordered message delivery.
tags:
- Queues
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QueueUpsert'
example:
queueName: my-queue
parallelism: 2
responses:
'200':
description: Queue created or updated
'401':
$ref: '#/components/responses/Unauthorized'
/queues/{queueName}:
get:
operationId: getQueue
summary: Get queue details
description: Retrieve configuration and status of a named queue.
tags:
- Queues
parameters:
- name: queueName
in: path
required: true
schema:
type: string
responses:
'200':
description: Queue details
content:
application/json:
schema:
$ref: '#/components/schemas/Queue'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteQueue
summary: Delete a queue
description: Delete a queue and all its pending messages.
tags:
- Queues
parameters:
- name: queueName
in: path
required: true
schema:
type: string
responses:
'200':
description: Queue deleted
'404':
$ref: '#/components/responses/NotFound'
/queues/{queueName}/pause:
post:
operationId: pauseQueue
summary: Pause a queue
description: Pause delivery for a named queue.
tags:
- Queues
parameters:
- name: queueName
in: path
required: true
schema:
type: string
responses:
'200':
description: Queue paused
/queues/{queueName}/resume:
post:
operationId: resumeQueue
summary: Resume a paused queue
description: Resume delivery for a paused queue.
tags:
- Queues
parameters:
- name: queueName
in: path
required: true
schema:
type: string
responses:
'200':
description: Queue resumed
components:
responses:
RateLimited:
description: Rate limit exceeded
headers:
Burst-RateLimit-Limit:
description: Maximum requests allowed in the current 1-second window
schema:
type: integer
Burst-RateLimit-Remaining:
description: Requests remaining in the current window
schema:
type: integer
Burst-RateLimit-Reset:
description: Unix timestamp when the rate limit window resets
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: Missing or invalid authentication token
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
QueueUpsert:
type: object
required:
- queueName
properties:
queueName:
type: string
description: Name of the queue (alphanumeric, hyphen, underscore)
parallelism:
type: integer
minimum: 1
description: Maximum number of messages to deliver in parallel (default 1)
ErrorResponse:
type: object
properties:
error:
type: string
description: Human-readable error message
PublishResponse:
type: object
properties:
messageId:
type: string
description: Unique identifier for the published message
example: msg_2XavMmRcJHJf7HkNtNqjfVf8uQe
url:
type: string
description: Destination URL the message will be delivered to
example: https://example.com/webhook
Queue:
type: object
properties:
name:
type: string
description: Queue name
parallelism:
type: integer
description: Configured parallelism level
paused:
type: boolean
description: Whether the queue is currently paused
pendingMessages:
type: integer
description: Number of messages currently pending delivery
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Bearer token obtained from the Upstash console at https://console.upstash.com/qstash. Alternatively, pass as query parameter `qstash_token`.
externalDocs:
description: QStash Documentation
url: https://upstash.com/docs/qstash/overall/getstarted