Skip to main content
POST
/
v2
/
publish
/
{destination}
Publish a Message
curl --request POST \
  --url https://qstash.upstash.io/v2/publish/{destination} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: text/plain' \
  --data '<string>'
{
  "messageId": "<string>",
  "deduplicated": true
}

Authorizations

​
Authorization
string
header
required

QStash authentication token

Headers

​
Content-Type
string

Content-Type is the MIME type of the message.

We highly recommend sending a Content-Type header along, as this will help your destination API to understand the content of the message.

Set this to whatever data you are sending through QStash, if your message is json, then use application/json. Some frameworks like Next.js will not parse your body correctly if the content type is not correct.

Examples:

  • application/json
  • application/xml
  • application/octet-stream
  • text/plain
​
Upstash-Forward-*
string

You can send custom headers to your endpoint along with your message.

To send a custom header, prefix the header name with Upstash-Forward-. We will strip prefix and send them to the destination.

HeaderForwarded To Destination As
Upstash-Forward-My-Header: my-valueMy-Header: my-value
Upstash-Forward-Authorization: Bearer Authorization: Bearer
​
Upstash-Method
enum<string>
default:POST

The HTTP method to use when sending the request to your API.

Available options:
GET,
POST,
PUT,
PATCH,
DELETE
​
Upstash-Timeout
string

Specifies the maximum duration the request is allowed to take before timing out.

This parameter can be used to shorten the default allowed timeout value on your plan. See Max HTTP Connection Timeout on the pricing page for default values.

The format of this header is <value><unit> where value is a number and unit is one of:

  • s for seconds
  • m for minutes
  • h for hours.
​
Upstash-Retries
integer

How many times should this message be retried in case the destination API returns an error or is not available.

The total number of deliveries is 1 (initial attempt) + retries.

If it is not provided, the plan default retry value will be used:

  • Free Plan: 3 retries
  • Paid Plans: 5 retries
​
Upstash-Retry-Delay
string

Customize the delay between retry attempts when message delivery fails.

By default, QStash uses exponential backoff. You can override this by providing a mathematical expressions to compute next delay. This expression is computed after each failed attempt.

You can use the special variable retried, which is how many times the message has been retried. The retried is 0 for the first retry.

Supported functions:

FunctionDescription
pow(x, y)Returns x raised to the power of y
exp(x)Returns e raised to the power of x
sqrt(x)Takes the square root of x
abs(x)Returns the absolute value of x
floor(x)Returns the largest integer less than or equal to x
ceil(x)Returns the smallest integer greater than or equal to x
round(x)Rounds x to the nearest integer
min(x, y)Returns the smaller of x and y
max(x, y)Returns the larger of x and y

Examples:

  • 1000: Fixed 1 second delay
  • 1000 * (1 + retried): Linear backoff
  • pow(2, retried) * 1000: Exponential backoff
  • max(1000, pow(2, retried) * 100): Exponential with minimum 1s delay
​
Upstash-Delay
string

Delay the message delivery.

The format of this header is <value><unit> where value is a number and unit is one of:

  • s for seconds
  • m for minutes
  • h for hours.
  • d for days.
​
Upstash-Not-Before
integer

Delay the message delivery until a certain timestamp in the future.

The format is a unix timestamp in seconds, based on the UTC timezone.

When both Upstash-Not-Before and Upstash-Delay headers are provided, Upstash-Not-Before will take precedence.

​
Upstash-Label
string

Label to assign to the message for easier identification and filtering in logs and DLQ.

​
Upstash-Flow-Control-Key
string

Flow Control Key to use for rate limiting messages.

Make sure you pass Upstash-Flow-Control-Value header as well to define the limits for the key.

​
Upstash-Flow-Control-Value
string

Flow Control parallelism, rate and period values to use for rate limiting messages for the given key.

Make sure you pass Upstash-Flow-Control-Key header as well to define the key.

​
Upstash-Deduplication-Id
string

Deduplication ID to use for de-duplicating messages.

If a message with the same deduplication ID was published in the last 10 minutes, the new message will be ignored.

​
Upstash-Content-Based-Deduplication
enum<string>
default:false

Enable content based deduplication.

When enabled, QStash will compute a hash of the message body and use it as deduplication ID. If a message with the same content was published in the last 10 minutes, the new message will be ignored.

Available options:
true,
false
​
Upstash-Callback
string

You can define a callback url that will be called after message delivery, either success or failure. See the content of what will be delivered to a callback here.

  • Callback URL must be prefixed with a valid protocol (http:// or https://)
  • Callbacks are charged as a regular message.
  • Callbacks will use the retry setting from the original request.
​
Upstash-Callback-Forward-*
string

You can send custom headers along with your callback message. To send a custom header, prefix the header name with Upstash-Callback-Forward-. We will strip prefix and them to the callback URL.

HeaderForwarded To Callback Destination As
Upstash-Callback-Forward-My-Header: my-valueMy-Header: my-value
Upstash-Callback-Forward-Authorization: Bearer Authorization: Bearer
​
Upstash-Callback-*
string

You can customize the callback message configuration.

See the Configuring Callbacks section to learn more.

HeaderDescription
Upstash-Callback-MethodHTTP method to use for the callback request. Default is POST.
Upstash-Callback-TimeoutTimeout for the callback request. Format is same as Upstash-Timeout header.
Upstash-Callback-RetriesNumber of retries for the callback request. Default is same as original message retries.
Upstash-Callback-Retry-DelayRetry delay for the callback request. Format is same as Upstash-Retry-Delay header.
​
Upstash-Failure-Callback
string

You can define a failure callback url that will be called when a delivery is failed. That is when all the defined retries are exhausted. See the content of what will be delivered to a failure callback here

  • Failure callback URL must be prefixed with a valid protocol (http:// or https://)
  • Failure callbacks are charged as a regular message.
  • Failure callbacks will use the retry setting from the original request.
​
Upstash-Failure-Callback-Forward-*
string

You can send custom headers along with your failure callback message. To send a custom header, prefix the header name with Upstash-Failure-Callback-Forward-. We will strip prefix and them to the failure callback URL.

HeaderForwarded To Callback Destination As
Upstash-Failure-Callback-Forward-My-Header: my-valueMy-Header: my-value
Upstash-Failure-Callback-Forward-Authorization: Bearer Authorization: Bearer
​
Upstash-Failure-Callback-*
string

You can customize the failure callback message configuration.

See the Configuring Callbacks section to learn more.

HeaderDescription
Upstash-Failure-Callback-MethodHTTP method to use for the callback request. Default is POST.
Upstash-Failure-Callback-TimeoutTimeout for the callback request. Format is same as Upstash-Timeout header.
Upstash-Failure-Callback-RetriesNumber of retries for the callback request. Default is same as original message retries.
Upstash-Failure-Callback-Retry-DelayRetry delay for the callback request. Format is same as Upstash-Retry-Delay header.

Path Parameters

​
destination
string
required

Destination can either be a valid URL where the message gets sent to, or a URL Group name.

  • If the destination is a URL, make sure the URL is prefixed with a valid protocol (http:// or https://)
  • If the destination is a URL Group, a new message will be created for each endpoint in the group.

Note that destination must be publicly accessible over the internet. If you are working with local endpoints, consider using QStash local development server or a public tunnel service.

Body

The raw request message passed to the endpoints as is

The body is of type string.

Response

Message(s) published successfully

  • Option 1
  • Option 2

Published to a URL destination

​
messageId
string

Unique identifier for the published message or the old message ID if deduplicated

​
deduplicated
boolean

Whether this message is a duplicate and was not sent to the destination.