API Examples

Use QStash via:

• cURL
• Typescript SDK
• Python SDK

Below are some examples to get you started. You can also check the how to section for more technical details or the API reference to test the API.

Publish a message to an endpoint

Simple example to publish a message to an endpoint.

• cURL
• Typescript SDK
• Python SDK

curl -XPOST \
    -H 'Authorization: Bearer XXX' \
    -H "Content-type: application/json" \
    -d '{ "hello": "world" }' \
    'https://qstash.upstash.io/v2/publish/https://example.com'

Publish a message to a topic

The topic is a way to publish a message to multiple endpoints in a fan out pattern.

• cURL
• Typescript SDK
• Python SDK

curl -XPOST \
    -H 'Authorization: Bearer XXX' \
    -H "Content-type: application/json" \
    -d '{ "hello": "world" }' \
    'https://qstash.upstash.io/v2/publish/myTopic'

Publish a message with 5 minutes delay

Add a delay to the message to be published. After QStash receives the message, it will wait for the specified time (5 minutes in this example) before sending the message to the endpoint.

• cURL
• Typescript SDK
• Python SDK

curl -XPOST \
    -H 'Authorization: Bearer XXX' \
    -H "Content-type: application/json" \
    -H "Upstash-Delay: 5m" \
    -d '{ "hello": "world" }' \
    'https://qstash.upstash.io/v2/publish/https://example.com'

Send a custom header

Add a custom header to the message to be published.

• cURL
• Typescript SDK
• Python SDK

curl -XPOST \
    -H 'Authorization: Bearer XXX' \
    -H 'Upstash-Forward-My-Header: my-value' \
    -H "Content-type: application/json" \
    -d '{ "hello": "world" }' \
    'https://qstash.upstash.io/v2/publish/https://example.com'

Schedule to run once a day

• cURL
• Typescript SDK
• Python SDK

curl -XPOST \
    -H 'Authorization: Bearer XXX' \
    -H "Upstash-Cron: 0 0 * * *" \
    -H "Content-type: application/json" \
    -d '{ "hello": "world" }' \
    'https://qstash.upstash.io/v2/schedules/https://example.com'

Set max retry count to 3

Configure how many times QStash should retry to send the message to the endpoint before sending it to the dead letter queue.

• cURL
• Typescript SDK
• Python SDK

curl -XPOST \
    -H 'Authorization: Bearer XXX' \
    -H "Upstash-Retries: 3" \
    -H "Content-type: application/json" \
    -d '{ "hello": "world" }' \
    'https://qstash.upstash.io/v2/publish/https://example.com'

Set callback url

Receive a response from the endpoint and send it to the specified callback URL. If the endpoint returns a response, QStash will send it to the failure callback URL.

• cURL
• Typescript SDK
• Python SDK

curl -XPOST \
    -H 'Authorization: Bearer XXX' \
    -H "Content-type: application/json" \
    -H "Upstash-Callback: https://example.com/callback" \
    -H "Upstash-Failure-Callback: https://example.com/failure" \
    -d '{ "hello": "world" }' \
    'https://qstash.upstash.io/v2/publish/https://example.com'

List all events

Retrieve a list of all events that have been published.

• cURL
• Typescript SDK
• Python SDK

curl https://qstash.upstash.io/v2/events \
    -H "Authorization: Bearer <token>"

List all schedules

• cURL
• Typescript SDK
• Python SDK

curl https://qstash.upstash.io/v2/schedules \
    -H "Authorization: Bearer <token>"