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

cURL

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

Typescript SDK

const client = new Client({ token: "<QSTASH_TOKEN>" });
await client.publishJSON({
  url: "https://example.com",
  body: {
    hello: "world",
  },
});

Python SDK

client = Client("<QSTASH_TOKEN>")
client.publish_json({
  "url": "https://example.com",
  "body": {
    "hello": "world",
  },
})
# Async version is also available

Publish a message to a topic

cURL

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

Typescript SDK

const client = new Client({ token: "<QSTASH_TOKEN>" });
await client.publishJSON({
  topic: "myTopic",
  body: {
    hello: "world",
  },
});

Python SDK

client = Client("<QSTASH_TOKEN>")
client.publish_json({
  "topic": "myTopic",
  "body": {
    "hello": "world",
  },
})
# Async version is also available

Publish a message with 5 minutes delay

cURL

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'

Typescript SDK

const client = new Client({ token: "<QSTASH_TOKEN>" });
await client.publishJSON({
  url: "https://example.com",
  body: {
    hello: "world",
  },
  delay: 300,
});

Python SDK

client = Client("<QSTASH_TOKEN>")
client.publish_json({
  "url": "https://example.com",
  "body": {
    "hello": "world",
  },
  "delay": 300,
})
# Async version is also available

Send a custom header

cURL

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'

Typescript SDK

const client = new Client({ token: "<QSTASH_TOKEN>" });
await client.publishJSON({
  url: "https://example.com",
  body: {
    hello: "world",
  },
  headers: {
    "My-Header": "my-value",
  },
});

Python SDK

client = Client("<QSTASH_TOKEN>")
client.publish_json({
  "url": "https://example.com",
  "body": {
    "hello": "world",
  },
  "headers": {
    "My-Header": "my-value",
  },
})
# Async version is also available

Schedule to run once a day

cURL

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'

Typescript SDK

const client = new Client({ token: "<QSTASH_TOKEN>" });
const schedules = client.schedules();
await schedules.create({
  destination: "https://example.com",
  cron: "0 0 * * *",
});

Python SDK

client = Client("<QSTASH_TOKEN>")
schedules = client.schedules()
schedules.create({
  "destination": "https://example.com",
  "cron": "0 0 * * *",
})
# Async version is also available

Set max retry count to 3

cURL

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'

Typescript SDK

const client = new Client({ token: "<QSTASH_TOKEN>" });
await client.publishJSON({
  url: "https://example.com",
  body: {
    hello: "world",
  },
  retries: 3,
});

Python SDK

client = Client("<QSTASH_TOKEN>")
client.publish_json({
  "url": "https://example.com",
  "body": {
    "hello": "world",
  },
  "retries": 3,
})
# Async version is also available

Set callback url

cURL

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

Typescript SDK

const client = new Client({ token: "<QSTASH_TOKEN>" });
await client.publishJSON({
  url: "https://example.com",
  body: {
    hello: "world",
  },
  callback: "https://example.com/callback",
});

Python SDK

client = Client("<QSTASH_TOKEN>")
client.publish_json({
  "url": "https://example.com",
  "body": {
    "hello": "world",
  },
  "callback": "https://example.com/callback",
})
# Async version is also available

List all events

cURL

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

Typescript SDK

const client = new Client({ token: "<QSTASH_TOKEN>" });
const events = await client.events()

Python SDK

client = Client("<QSTASH_TOKEN>")
events = client.events()
# Async version is also available

List all schedules

cURL

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

Typescript SDK

const client = new Client({ token: "<QSTASH_TOKEN>" });
const schedules = client.schedules();
const scheds = await schedules.list();

Python SDK

client = Client("<QSTASH_TOKEN>")
schedules = client.schedules()
scheds = schedules.list()
# Async version is also available