OpenAPI Specification
openapi: 3.0.3
info:
title: QStash Dead Letter Queue Messages 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: Messages
description: Publish and manage messages
paths:
/publish/{destination}:
post:
operationId: publishMessage
summary: Publish a message
description: Publish a message to a destination URL or URL Group. QStash will store the message durably and deliver it to the destination with automatic retries on failure.
tags:
- Messages
parameters:
- name: destination
in: path
required: true
description: Destination URL or URL Group name
schema:
type: string
example: https://example.com/webhook
- name: Upstash-Delay
in: header
description: Delay message delivery by this duration (e.g. "5m", "1h")
schema:
type: string
example: 5m
- name: Upstash-Retries
in: header
description: Number of retry attempts on delivery failure (0-5)
schema:
type: integer
minimum: 0
maximum: 5
- name: Upstash-Retry-Delay
in: header
description: Delay expression between retries (supports math functions like pow, sqrt)
schema:
type: string
- name: Upstash-Callback
in: header
description: URL to receive callback after successful delivery
schema:
type: string
format: uri
- name: Upstash-Failure-Callback
in: header
description: URL to receive callback on delivery failure after all retries
schema:
type: string
format: uri
- name: Upstash-Deduplication-Id
in: header
description: Manual deduplication ID; duplicate messages within 10 minutes are ignored
schema:
type: string
- name: Upstash-Content-Based-Deduplication
in: header
description: Automatically deduplicate based on destination, body, and content headers
schema:
type: boolean
- name: Upstash-Timeout
in: header
description: Timeout for the delivery request (e.g. "30s")
schema:
type: string
- name: Upstash-Not-Before
in: header
description: Unix timestamp before which delivery should not occur
schema:
type: integer
- name: Upstash-Schedule-Id
in: header
description: Unique schedule ID; used to create or overwrite a schedule
schema:
type: string
- name: Upstash-Cron
in: header
description: CRON expression to schedule recurring delivery (e.g. "0 0 * * *")
schema:
type: string
- name: Upstash-Method
in: header
description: HTTP method to use when calling the destination (default POST)
schema:
type: string
enum:
- GET
- POST
- PUT
- PATCH
- DELETE
- HEAD
requestBody:
description: Message payload to deliver to the destination
content:
application/json:
schema:
type: object
additionalProperties: true
example:
hello: world
application/octet-stream:
schema:
type: string
format: binary
text/plain:
schema:
type: string
responses:
'201':
description: Message published successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PublishResponse'
'202':
description: Duplicate message detected; existing message returned
content:
application/json:
schema:
$ref: '#/components/schemas/PublishResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
/batch:
post:
operationId: batchPublish
summary: Publish multiple messages in a single request
description: Publish multiple messages in a single batch request. Messages can target different destinations, URL Groups, or queues. If one message fails, the others still proceed.
tags:
- Messages
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BatchMessage'
example:
- destination: https://example.com/endpoint1
body: '{"event":"ping"}'
headers:
Content-Type: application/json
- destination: https://example.com/endpoint2
body: '{"event":"pong"}'
responses:
'200':
description: Batch result; includes per-message success or error
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BatchResponseItem'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/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:
- Messages
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'
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'
BadRequest:
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
BatchMessage:
type: object
required:
- destination
properties:
destination:
type: string
description: URL, URL Group name, or queue destination
url:
type: string
description: Alternative to destination for direct URL targeting
urlGroup:
type: string
description: URL Group identifier for fan-out delivery
queue:
type: string
description: Queue name for FIFO delivery
headers:
type: object
additionalProperties:
type: string
description: Request headers to include (supports Upstash-* headers)
body:
type: string
description: Message payload as string (JSON, XML, etc.)
delay:
type: string
description: Delay before delivery (e.g. "5s", "1m")
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
BatchResponseItem:
type: object
properties:
messageId:
type: string
description: Message ID for successfully queued messages
url:
type: string
description: Destination URL
error:
type: string
description: Error message if this particular batch item failed
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