POST
/
v2
/
schedules
curl -XPOST https://qstash.upstash.io/v2/schedules \
  -H "Authorization: Bearer <token>"
{
  "scheduleId": "scd_1234"
}

Request

destination
string
required

Destination can either be a topic name or id that you configured in the Upstash console, or a valid url where the message gets sent to. Make sure the url is prefixed with a valid protocol (http:// or https://)

body
string

The raw request message passed to the endpoints as is

Content-Type
string

ContentType 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.

For example application/json, application/xml, application/octet-stream, text/plain

Upstash-Method
string
default: "POST"

The HTTP method to use when sending a webhook to your API.

Upstash-Delay
string

Delay the message delivery.

Format for this header is a number followed by duration abbreviation, like 10s. Available durations are s (seconds), m (minutes), h (hours), d (days).

example: ”50s” | “3m” | “10h” | “1d”

Upstash-Retries
int
default: 3

How often should this message be retried in case the destination API is not available.

The total number of deliveries is therefore capped at 1 + retries

Leave this empty to use the default value, (free tier: 3, paid tier: 5)

The backoff duration in seconds is calculated as follows: n is the number of times the task has been retried.

min(86400, e ** (2 * n))

Upstash-Callback
string

You can define a callback url that will be called with the response from the destination API. Callbacks are experimental, and the API might change in the future!

  • The 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-Forward-*
string

You can send custom headers along with your message.

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

example: “Upstash-Forward-My-Header: my-value” -> “My-Header: my-value”

Upstash-Cron
string

Cron allows you to send this message periodically on a schedule.

Add a Cron expression and we will requeue this message automatically whenever the Cron expression triggers. We offer an easy to use UI for creating Cron expressions in our console or you can check out Crontab.guru.

Note: it can take up to 60 seconds until the schedule is registered on an available qstash node.

Example: */5 * * * *

Response

scheduleId
string
required

The unique id of this schedule. You can use it to delete the schedule later.